22

Commenting nowadays is easier than ever. In Java, there are some nice techniques for linking comments to classes, and Java IDEs are good at making comment shells for you. Languages like Clojure even allow you to add a description of a function in the function code itself as an argument.

However we still live in an age where there are often obsolete or poor comments written by good developers - I'm interested in improving the robustness and usefulness of my comments.

In particular I'm interested in Java/Clojure/Python here, but answers don't need be language-specific.

Are there any emerging techniques that validate comments and automatically detect either "flimsy" comments (for example comments with magic numbers, incomplete sentences, etc..) or incorrect comments (for example, detecting mispelled variables or the like).

And more importantly: Are there accepted "commenting-policies" or strategies out there? There is plenty of advice out there on how to code - but what about "how to comment?"

yannis
  • 39,547
  • 40
  • 183
  • 216
jayunit100
  • 379
  • 2
  • 7
  • One "fun" idea I've had with enforceable "comments" is that in some cases, it is possible write our comments as code and `assert` calls. Not "this optimized function is actually the same as [algorithm description]" but a separate function definition with the simplest algorithm and an `assert optimized_function(...) == clearest_function(...)`. – mtraceur Feb 20 '23 at 07:18

6 Answers6

42

  • Names/documentation should tell you what you are doing.

  • Implementation should tell you how you are doing it.

  • Comments should tell you why you do it the way you do.

ratchet freak
  • 25,706
  • 2
  • 62
  • 97
  • 7
    comments should also tell you why you are _not_ doing it another way - i.e. important design choices - because future maintainers will not have this information otherwise. –  Jan 15 '12 at 08:39
  • 3
    I believe there are many times a comment should say WHAT you are doing too. This idea of only "why" comments is an anti-pattern in my opinion. It is a myth that you can write all code clear enough that any programmer can understand it at a glance, and my experience is most programmers who think they write clean code don't. It's the same as saying, "I don't have to name this function descriptively because anyone can just read the code in the function to see what it does." - that doesn't make sense either, does it? – dallin Sep 03 '13 at 21:05
  • 3
    @dallin if your code isn't clear about what it is doing; consider refactoring it. otherwise add a comment explaining why it's implemented like that (which happens to also explain the how better). Your comparison with descriptive names is apples/oranges, a descriptive name makes it clear *where the function is used*, and you may not have access to the source code of the function. – ratchet freak Sep 04 '13 at 07:33
  • @dallin: "It is a myth that you can write all code clear enough that any programmer can understand it at a glance", Uncle Bob would want to have a word with you. -- "I don't have to name this function descriptively because anyone can just read the code in the function to see what it does.", giving good and clear names to variables and methods is exactly how programmers should make clear what their code is doing! – klaar Jul 23 '18 at 08:23
15

This might be controversial, but my advice would be to write as FEW comments as possible. Use nice, clear class names, variable names and method names instead. Write your code in the clearest way that you can; and consider this to be the most important attribute of your code (other than that it meets its requirements). Only write a comment if you've made a method as clear as you possibly can, and you still think it requires further explanation.

And have an organisational practice, that whenever anyone changes a class in any way, they have to make sure the comments are still all correct.

Dawood ibn Kareem
  • 1,852
  • 12
  • 14
  • 1
    This is a good start, but I think to satisfy the OP's question you will need to write something that addresses his actual concerns with respect to automatic validation. – Robert Harvey Dec 29 '11 at 00:24
  • 2
    +1 - I also think that comments should only be used to explain *why* code has been written. I know what `if (a == b) then c();` does, but if I don't know *why* it does it - that's when a comment should be used :) – Deco Dec 29 '11 at 01:29
  • Deco - I agree completely. Comments are good when I want to understand how a particular method fits into the process as a whole. In other words, WHY you'd call this method, or WHY it does what it does. – Dawood ibn Kareem Dec 29 '11 at 05:31
  • In addition to make written code clear, we should also make sure to retain (code-level) ideas, thoughts, etc. using TODO comments. E.g. if you see a function/class is able to handle current data size properly, but potentially will fail to handle load after 2 years, then make sure to write your observation there using TODO comment. Future developers will indeed appreciate your efforts. Don't ever try to note these things in a separate txt/word document, while writing code, no one really refers such documents. – TechCoze Dec 29 '11 at 10:54
  • see also: [“Comments are a code smell”](http://softwareengineering.stackexchange.com/q/1/31260) – gnat Nov 08 '16 at 07:22
5

I'm not sure about other languages, but python allows you to write doctests which are a form of self-validating comments. Of course, they shouldn't be used in place of real unit testing, but are a quick and easy method of documenting specific functions that may not be as obvious as they should be. They come with the added benefit of being able to execute the comment tests to verify that comments are still correct (at least the portion of them that contain tests).

Josh Smeaton
  • 1,162
  • 7
  • 9
3

One of the most authoritative location to find how to use code comment to generate documentation automatically is surely doxygen. Though there could me more of such tools.

This defines the standard of comment writing which should be followed to automatically generate documentation. However, this gives more of a structure but doesn't validate semantically; for example it can't check if you have used misleading english to describe the purpose of a function!

While, this is the best thing that make comments structured, personally i feel there is more documentation needed to make code more maintainable as such. Some time back there was a question in P.SE Can code be the documentation in open source developer tools? How frequently is it? Of course, This applies to non-open-source projects as well.

To make code more maintainable - it is practically more important that there exists a external documentation that helps create structure of how to treat code, and then comments inside the code should be restricted to see

I think, if you want to define the policies for comment writing you should include as a holistic approach included in the coding standard. See this: What could be some pitfalls in introducing a style guide and documentation generating software in a development team?

Usually a comments constitutes less than 5% of the code. And in practice while code-reviews itself draws much less attentions (over other aspects of development) is is practically difficult that comments are also reviewed.

albert
  • 155
  • 5
Dipan Mehta
  • 10,542
  • 2
  • 33
  • 67
  • 1
    I disagree with the last sentence here. I've just finished a contract, working under a team leader who gave very detailed reviews. His reviews always included the comments - how they were worded, whether the variable names were correct, whether they contained all the information that a future developer might want to know. Before long, I knew what he expected to see in each comment, and was able to produce comments to his standard. So, provided it's organisational policy to have code reviews, and include comments in the code review, then it will happen. – Dawood ibn Kareem Dec 29 '11 at 21:06
  • This is usually the only kind of comment I write, especially for methods to document what goes in and what comes out of it (I work with loosely typed languages). – DanMan Apr 23 '14 at 17:54
2

Are there any emerging techniques that validate comments and automatically detect either "flimsy" comments (for example comments with magic numbers, incomplete sentences, etc..) or incorrect comments (for example, detecting mispelled variables or the like).

There is a well-know technique - it is called "code-review", and has a sister named "pair-programming". Don't expect anything "automagically" here.

And more importantly : Are there accepted "commenting-policies" or strategies out there ? There is plenty of advice out there on how to code --- but what about "how to comment?"

"Code complete" contains not only all about how to code, but also chapters on "how to comment", especially on how to write self-documenting code.

Doc Brown
  • 199,015
  • 33
  • 367
  • 565
  • +1 for Code Complete. Clean Code by Robert Martin also has a good chapter on writing useful commends. I'm not sure about Java world but in .NET world we have Resharper, which can 'automagically' validate references to code elements in comments :) – MattDavey Dec 29 '11 at 09:58
0

Specific to Java one source I've enjoyed is Oracle's How to Write Doc Comments for the Javadoc Tool:

This document describes the style guide, tag and image conventions we use in documentation comments for Java programs written at Java Software, Sun Microsystems.

And Item 44: Write doc comments for all exposed API elements:

If an API is to be usable, it must be documented. Traditionally API documentation was generated manually, and keeping it in sync with code was a chore. The Java programming environment eases this task with the Javadoc utility. Javadoc generates API documentation automatically from source code with specially formatted documentation comments, more commonly known as doc comments.

from Effective Java 2nd Edition.

yannis
  • 39,547
  • 40
  • 183
  • 216
EGHM
  • 109
  • 2