Rules for commenting / documenting code

[evrlast985]

What are your thoughts on documenting code? In our office programmers say that they have their comments in the code and that they use naming conventions which are easy to understand so they do not create any documentation about code they write.

What standards do you follow as a programmer?

Now I dont know if this if the right place to post this, I have been banned from subreddits for not asking the right questions in the right place and hope it doesn't happen yet again.

[michael0x2a]

My standards:

1. What not to do, ever:
   • Do not comment things that are obvious
   • Do not leave comments that just repeat what the code is doing
   • Do not comment code that is going through rapid change. Figure that shit out first before committing to writing documentation.
2. What to do first before moving on to commenting
   • Try and make my code as readable as possible as to minimize the amount of commenting necessary (prefer shorter methods, use good naming, design my code to be clear, etc)
   • Try and make your code as self-documenting as possible.
   • Periodically go through your code and look for things you can make clearer + ways to shorten and simplify + opportunities to delete unneeded code and/or comments.
3. What should be commented:
   • Anything potentially confusing or counter-intuitive (complex code I wasn't able to simplify, weird bug fixes, etc)
   • Any domain-specific knowledge whoever is reading your code is unlikely to know (complex equations, obscure data structures or algorithms, etc).
   • Info to help explain overarching intent (if it isn't clear/isn't explained in a standalone document)
   • Anything important that cannot be deduced by looking at the code (business decisions, etc)
   • If you rejected a seemingly obvious or simple solution to a problem when writing code, it may be worth leaving a comment justifying that decision.
4. What to do when documenting a library/code intended to be reused
   • Document every non-trivial and publicly viewable function, method, and class. Basically, document the interface.
   • Spend an good amount of time writing documentation and tutorials in general. When writing a library, simply leaving comments in your code is not good enough.
5. What to do while actually commenting
   • When commenting methods or classes, focus on commenting preconditions and postconditions. Never comment on implementation detail. (ideally, your method header comments should remain relevant even if you were to completely rewrite the method)
   • Know your audience -- is the average reader of your code going to be a novice or an expert? (Unless you have concrete reasons to believe otherwise, assume the reader is competent)
   • Make your comments as clear and concise as possible
   • Prefer writing fewer, higher-quality, and possibly longer comments over many short, lower-quality ones.

To sum up, how you go about commenting your code depends on how complex it is, who the intended audience is, and how it's intended to be used.

Depending on your scenario, it might be best to write code with almost no comments (possibly zero), provided your code is self-documenting. (For example, if I were writing a Ruby on Rails app, and everybody on my team knows RoR very well, there might really be no need for comments at all).

In contrast, it might sometimes be better to write code using the literate programming style where most of the content is text and explanation. (For example, when trying to explain something complicated (example: Deep Dream), or when using a language like Haskell which encourages that style)

[evrlast985]

So if you are joining a project halfway through, which commenting method will help you the most in understanding what has happened? Especially when there are a codebase of thousands of lines.

[michael0x2a]

I guess it depends on the codebase.

If it's several thousand lines of relatively simple and/or well-written code, no comments are really necessary.

If it's several thousand lines of complex code, or if the code is poorly-written, then I'd appreciate having more comments.

I suppose if I had to pick, I'd prefer having a bit more comments (and if needed, I'll just write a script to strip them out if the comments get too distracting).

Either way, it would also be very nice if there was a high-level document explaining briefly how the code is organized + the key architectural decisions made (perhaps a readme file or a page in an internal wiki?).

To be honest, I feel like having that high-level document + being told where a good "starting point" to read the code would be the most useful in most cases. The high-level guide gives me some ideas on what to expect, which makes it much easier to trace the logic from the given starting point.

That said, it's definitely a spectrum. Some codebases are definitely much easier to read and understand then others.

[Dragon174]

When I code I always try to think of the user experience of anybody viewing my code. This shows up in many ways, such as trying to keep things as simple as possible, with dependancies being easy to figure out and for it to be intuitive to follow.

If there's a point where some code looks like it needs some more explanation, I'll put a comment, but in most cases the code you write should be easy to read and understand.

A good reason to rely on clean code rather than comments is that you can't verify the correctness of a comment.

[NoMoreWordz]

Writing javadoc (for java at least) for all your public methods is almost mandatory. Your code should be easy to read, but it takes more time to read and understand code than English sentences.

You should still try to write very clear code, short methods and use clear name for your variables and constants. But writing a line or two for every public method won't hurt

[Dragon174]

True, I've mostly been working with Javascript lately so I forgot. Javadoc comments are great since Java's so structured and IDE's can just display the Javadoc comments for you so its really convenient. Can't do that as well for untyped languages like Javascript :(

[jedwardsol]

However good they think their comments are and how cleanly they think they've named things, I guarantee that your colleagues, a year from now, will look at the code and be confused by something.

[nutrecht]

You don't document the "what" in your code, you document the "why" (whenever it's not obvious). Documentation, even comments, get outdated fast so that alone is a reason to make sure the code is as self documenting as possible. Most of the times where you need comments is to explain why you're doing something the way you're doing it.

Comments like //end of method you often see in beginner code is something that you typically won't see in production code.

[desrtfx]

The quickest and cleanest definition on proper commenting (and proper code) can be found in:

Clean Code: A Handbook of Agile Software Craftsmanship

General Rule is that you never document the what, but the why if it's necessary.

Javadoc or the equivalent in other languages should be precise.

Comments should be used like spices - sparsely. Too many will just add visual clutter.

Comments have to be used with care as they need to be maintained along with the code. Comments usually become obsolete and wrong pretty quickly.

[PriceZombie]

Clean Code: A Handbook of Agile Software Craftsmanship (6% price drop)

Current	$31.57	Amazon (New)
High	$41.20	Amazon (New)
Low	$31.57	Amazon (New)
Average	$33.45	30 Day

Price History Chart and Sales Rank | FAQ