Tufts CS 117 (Fall 2022):
Internet-scale Distributed Systems

Tufts CS 117: Coding Standards and Guidelines

Overview

Good programmers take pride in producing code that is well organized and easy for others to understand. In CS 117 your programming scores will be reduced, in some cases significantly, if your code is not easy to follow: this may take more effort than you expect, but we are serious about it. You are at a level where the work you do should always be at or near professional standards, and that means taking great care to produce beautiful source code.

The best coding standards are aimed at meeting the needs of those who will work with your code, and not every audience is the same. In 117 your code is intended for you and your partners, but especially for the CS 117 graders. Reading your code should not be a test of their C++ or networking expertise: if anything in your code is subtle, it should be explained. It should be easy to find which part of your code does what by skimming.

Samples

Because they are intended as learning tools, the CS 117 samples are somewhat more heavily commented than I would typically do, but the general style and attention to detail is typical of what I would expect on the commercial projects I've helped build. Take a look at some of the framework code (maybe c150dgmsocket.h and src/c150dgmsocket.cpp in the /comp/117/files/c150Utils/ dir) and it may give you some ideas.

You are not expected to comment as heavily as I do in the samples, but you are expected to deliver source that is well organized and easy to read. Don't hesitate to use comments or to use vertical spacing if it helps to make the structure or function of the code easier to follow.

Specific coding requirements

The following is always required:

That said, writing clear, consistent and beautiful code trumps any specific detailed rule.

Commenting and Source Code Layout

Commenting and layout of your source code is important! Use comments whenever they make your code easier to understand, and also to make it easy for new readers to immediately spot the parts of the code they're looking for. As you write your code consider: who is your audience? Who will be reading and maintaining your code?

For our sample code the the audience is you and the purpose is to teach you as quickly as possible to use the framework. Thus, as previously noted, the samples are commented somwhat more heavily than would be typical for other purposes. The framework files in c150Utils are closer to what I would do for commercial code (which I expect to maintained and used by other programmers), but even those are somewhat over-commented to help provide extra information for students using the framework.

Unlike some other very good programmers, I do tend to err on the side of more commenting and trying to make sure that the source is easy to skim. Thus, it's easy in the sample pingclient to skim to the checkAndPrintMessage routine without picking through code details. That's because the starts of functions and their names are always set off in a way that's easy to spot. That sort of clean formatting is a good thing to do, especially if code is more than a page or so long. Specific suggestions:

Again, you are not expected to comment nearly as generously as in the samples. You are expected to write clear, well organized code, and to use comments as needed to achieve that.

NEEDSWORK

The sample above happens to show a trick I picked up 30 years ago while working on the LOCUS distributed system. If there's anything you're not sure about or that needs more work, leave a note with a very clear marker that's easy to find with a search. The keyword we used and that I still use is: NEEDSWORK.

Of course, if your NEEDSWORK says that your program is totally broken we can't give you a lot of credit, but mostly your grade will go up rather than down if we see that you understand the limitations of your code.

The real value is that before you submit you'll be able to search for all the things that weren't perfect and decide which to fix. For the ones you don't, definitely leave the NEEDSWORK marker (or whatever you choose). Weeks later, when you hit a bug, these things can save a huge amount of time. Your program crashes, you open the code, and right there is the comment that says: "NEEDSWORK: not handling buffers > 1000bytes". I only see this occasionally in commercial work, but I encourage it as key to the coding standards for any team that I lead.