Slashdot Mirror
What is Well-Commented Code?
WannaBeGeekGirl queries: "What exactly is well-commented code anyway? Can anyone suggest resources with insight into writing better comments and making code more readable? After about six years in the software development industry I've seen my share of other people's code. I seem to spend a lot of time wishing the code had better (sometimes _any_) comments. The comments can be frustrating to me for different reasons: too vague, too specific, incoherent, pointing out the obvious while leaving the non-obvious to my imagination, or just plain incorrect. Poorly or mysteriously named variables and methods can be just as confusing. In a perfect world everyone would follow some sort of coding standards, and hopefully those standards would enforce useful comments. Until then, any suggestions for what you, as a programmer, consider to be good/useful/practical comments? Any suggestions for what to avoid? Also, I usually work with C++ so any resources/comments specific to that language would be too."
I can absolutely recommend a book called Code Complete. Yes, it is published by Microsoft, but it is an invaluable language-agnostic guide to writing software that includes heavy doses of common sense regarding commenting, coding styles etc.
The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other. Donald Knuth. "Literate Programming (1984)" in Literate Programming. CSLI, 1992, pg. 99.
This post was compiled with `% gec -O`. email me if you need the sources
Tools like javadoc, or maybe better in your case doxygen can really help when it comes to commenting code... the idea is pretty much that you place a documentation comment before each function, or class, and so on, which usually makes the entire thing much easier. Having done that, I've found that only a few more non-obvious parts have to be commented within the actual functions.
Tomorrow will be cancelled due to lack of interest
I also have seen my share of other people's code.
// increment i
Quality of comments varies.
I've seen code from the 'hardcore hacker', who believes that the statements themselves suffice as comments - 'the code is intuitively obvious, and it comments itself'.
I've also seen code from complete lamers, who dilute the code terribly with irrelevant shit:
i++;
Over the years, I've noticed that composition of code, and commenting/documentation of code, tend to draw on two different parts of the brain.
Often, I find myself in a 'zone', where the code flows freely, and where commenting code feels like a total distraction.
Other times - for instance, when I'm hunting an elusive bug, I find a different part of the brain kicking in - and at that stage, I find it easier, even pleasurable, to add meaningful comments, to change indenting, variable names etc, as if I'm narrating the code to someone else.
I guess it's a matter of balance, and using the right mental faculties at the right time.
A good rule of thumb is to imagine that someone else is sitting beside you, someone less acquainted with the task than yourself (eg a non-technical manager). Imagine you're explaining to him/her how the code works, and put these explanations in the code as succinct yet clear comments. Imagine this person asking you, 'what's that variable'. Don't be afraid of global search'n'replace of identifier names across all the applicable files. And imagine this person sometimes getting up and leaving you in peace, so you can have those precious moments to hack to your heart's content.
In conclusion, I feel that much of a person's personality can be read from one's code. Is someone fundamentally easygoing and helpful, and caring about others? Or is someone a complete egotist, emotionally shut down almost to the point of autism? In my mind, the ability of code to communicate its intent and methods to other programmers is almost as important as the code successfully performing its task, since its communicability directly affects the ability and interest of others in working on it, and thus its openness to manpower leverage.
-- In the beginning was the WORD, and the WORD was UNSIGNED, and the main(){} was without form and void...
comes this advice:
Comments are good, but there is also a danger of over-commenting. NEVER try to explain HOW your code works in a comment: it's much better to
write the code so that the _working_ is obvious, and it's a waste of time to explain badly written code.
Generally, you want your comments to tell WHAT your code does, not HOW. Also, try to avoid putting comments inside a function body: if the
function is so complex that you need to separately comment parts of it, you should probably go back to chapter 4 for a while. You can make small comments to note or warn about something particularly clever (or ugly), but try to avoid excess. Instead, put the comments at the head
of the function, telling people what it does, and possibly WHY it does it.
--- Hot Shot City is particularly good.
It is not only executeable code that can benefit from comments. In particular any numeric fields should have a units comment (e.g. m or m/S). It can be quite time consuming to deduce the units from the code.
Too many comments can be just as much a sign of bad code as too few. When a function or methodis filled with paragraph-long comments explaining what it does, that's often a sign that you should rename some variables, or factor out parts of the work into separate, well-named functions or methods.
Don't be afraid of having long, descriptive names. They go a long way towards making the code more clear without using comments.
Sometimes, even if you break a function into several subfunctions that it calls in order and which are called nowhere else, that can help readability, as long as you draw the boundaries intelligently.
*foo means 'foo dereferenced'. In a type declaration, 'int foo' means 'foo is an int', so 'int *foo' means 'foo dereferenced is an int'. And, therefore, foo is a pointer to an int.
So, it's actually quite logical. In this: 'char foo, *bar', we declare that two things have type 'char': foo, and the thing that bar points to.
I strongly disagree. The proper delineation of a function or method is the operation that it abstracts, not how long it is.
If a subroutine is only called once, and doesn't cleanly abstract some idea (i.e., if you can't tell me what it does in one simple sentance), it should not be in a separate subroutine.
I've seen too much code written in the manner you suggest, that makes the reader bounce around from function to function to function for no reason other than "otherwise that function would be more than 30 lines".
If I have to maintain such code I always refactor it into one subroutine.
Tom Swiss | the infamous tms | my blog
You cannot wash away blood with blood
I use Vim primarily, and I'm beginning to switch to using Emacs for coding.
Vim has the most wonderful autocomplete hotkeys; type the beginning of the function/variable name, then press Ctrl-p to search up and Ctrl-n to search down through the file, buffers, etc. Now, long variable names are actually usable for 80wpm typists like me. (I'm around 40-50 for plain text).
Does anyone know what the equivalent (or at least sorta-equivalent) commands are in Emacs?
-Chris
...who make reviewers like me stare at computer screens for endless hours trying to figure out how the hell your computer code is supposed to work.
// Creates hash table ". Question: Where does that leave me? When I find out that there's some problem in the hash algorithm, I have to dig through 200 lines of code to find some freakin' bug that is described only by "Creates hash table." Your example of why comments don't need to be made is a poor one:
// increment loop counter
Comment sparsely. Do not sprinkle your code with comments. Especially do not use comments like
Yea, I can already picture your programming style. You'd make a 200-line function with the only comment being "
loopCounter++;
That is adding zero value.
Yes, because it's one line of code, and the code is described through the variable. But when sifting through lines of code, you often find beautiful works like iHateMyJob++; or fuckMyBoss--; to name a few. And needless to say, they're uncommented in the code. Until computer code can be written bug free in complete English sentences (aka Never), the rest of your team of workers needs to understand what your code does.
Personally, I make sure every function says what goes into it, what comes out of it, and what setup (variables, etc.) need to be made for it to be called. I do not comment every single line of code, but I do make sure that every line is accounted for by descriptive sentences, explaining the task that I wish to accomplish as well as what variables / registers / actions I take to accomplish the task.
Every time someone has to change some code, you've just forced them to double their workload, and change some comments too.
Okay, this just pisses me off. You didn't mean what you said. Here's what you meant to say:
Every time I have to change some code, you've just forced me to double my workload, and change some comments too.
I can assure you, from a reviewer's point of view, comments SAVE my time from trying to understand what each piece of code is trying to accomplish. Commented code may make you work extra time to detail the lines of code (I do admit, some programmers are quite tallented at keeping track of every single line of code in their head as they work on it on the computer), but it saves tremendous amounts of time once that chunk of code needs to be integrated with other chunks of code into the final product.
Take a look at these files. This project is basically an example of what not to do. It's faggotted up like a twelve-year-old schoolgir's notebook, to borrow a phrase from The Onion. In particular,
That should be obvious from the "public static void main (String argv[])".
As a fourth year student at the University of Oklahoma in the MIS program, I have taken a few programming languages (including C and Fortran) and I have had different instructors attempt commenting quite differently. In my very first programming course, my C instructor didn't really care about comments, he made really no attempt to inform us of how/what/where to correctly comment, as for variable names, we could basically use whatever we wanted --seeing that I didn't know any better then, this is what I did (and have had problems remembering what this code was used for ever since.)...After that mess, however, I took a Fortran 95 class with a professor in the CS dept here--he had very stringent requirments concerning every aspect of the code (including documentation) which I found very helpful (however time consuming to do). I don't know if this applies to non-procedure languages, however, in Fortran, we were required to have a variable declaration section in which constants were listed first (with REALs before INTEGERS), then local variables (REALs before INTEGERs), then external variables for functions/subroutines, etc. We could not use any literal constants in the body of the program (except character strings) --we could only use named constants (declared in the variable section). We also had to make sure that our variable names had to make sense to someone who knows nothing about the program (which could make variable names incredibly long, however, in one's drunken stupor--one can still understand what they mean).
We also had to comment every line of Fortran code (that was meaningful) and before declaring our variables, we had to create a comment section that clearly listed and defined each and every variable name. At the beginning of the program and before each function/subroutine we also had to have a comment box stating the name of the program (function, etc.) and description of what it did. (for functions we also had to list any arguements being used.)
Although all of this commenting was rather time consuming and increased the length significantly, I found it was incredibly helpful when I have had to try to figure out the logic again.
What you are describing (and quite well) is the top-down programming practice. There's a big problem with it, though: in the real world, things change. As others have pointed out, you can't be guarenteed to be able to hammer down a specification that will be satisfactory for a year, or a month, sometimes even a week or a day. Some customer, some manager, or whoever, will demand a change in the final product. What will you do then? You will have to change your entire structure around and that can be extremely difficult.
Fortunately there are other ways of approaching the problem. One of them is called the bottom-up approach. The basic idea is to create a mini-language that one can better formulate your problem in, and then start putting the pieces together. This is complimented by dynamic semantics that languages such as Common Lisp or Smalltalk have. Incremental, interactive compilation and development is well supported by these environments. The code winds up being self-documenting because you wrote it in a mini-language! Weirdly obfuscated--but necessary--as well as commonly used pieces of code can be abstracted with Lisp macros. Changing your data-structures is no problem, already in-use data-structures can be dynamically updated (and you can control how it happens). Errors are handled by the exceptional condition system (no pun intended) and the program can be continued from where you left off, after being fixed. Always you have a working, running codebase.
Those who do not know the past are doomed to reimplement it, poorly.
I once worked with a guy whos favorite variable and was asdf (Just roll your left hands fingers across the keyboard), and when he needed another he'd roll his fingers the other way(fdsa). It was maddening to debug. I find it useful to comment each section with what the code chunk expects in terms of data in, what it does with this data, then how and where it returns the data. I sometimes also note my thought process in writting the code this way. There are also times when I don't comment the code at all... especially if it's a chunk for an embedded box with limited storage. I do write docs for it, but they're stored elsewhere. -Just my $.02
Why worry? Each of us is wearing an unlicensed "nucular" accelerator on his back.
Sig changed for readability by G.W.
I haven't had time to read through this massive reply list, but I'll just throw my own 2 cents in...
I've found that variable names are important. I make a point of making concise and clear variable names that describe that is happenening, i.e. HitCount rather than FuckingVarCounter. I use scope names from Hungarian(g_, m_) for global and classes, but avoid prefixing types(i, l, f, etc.), mainly because if a var type is cahnged later it gets really irritating. Of course, Replace All is useful too...In any case, I feel that the name of a variable should also make it's type obvious(e.g. NumSheep should be an integer).
As for comments, I use them to explain algos that are not really basic(not like a simple loop) and generally explain _why_ something is being done. I use newlines to divide code inside functions into logical blocks, rather than cutting it into senselessly multiple functions.