6

When trying to learn about proper comment practices, I found a lot of conflicting opinions, and it's obviously a very subjective topic. So I'm not going to ask "Should I comment, or should I not?"

The question I'd like to pose is, for me, as a self taught developer interested in applying for programming jobs in the future, a vital one: Of the two strategies

"Comment the right code in the right way." - (comments where needed)

and

"Instead of writing comments, write more readable code." - (if you need comments, your code is bad)

are both valid strategies in programming?

If I submit an application with code samples including masterfully written code and no comments, are experienced programmers likely to be familiar with that approach?

I'm not asking "Will the specific guy reading my application like my coding style", obviously no one can guess that, I'm just looking for a general answer as to whether both practices are common, or if my code will be seen as terrible across the board.

13

Your question implies a dichotomy that doesn't exist.

Should you write cleaner code, if doing so will make it clear enough where you don't have to document it? Absolutely.

Should you write comments and otherwise provide documentation, when it will improve the clarity and understanding of the code? Of course.

Why are these two things not mutually exclusive?

  1. Some of the code that you write will favor better performance over high readability.
  2. Architecture is not self-documenting. While code in isolation is generally fairly easy to understand if it's written cleanly, the architecture surrounding it is not always.
  3. Design decisions are not always self-evident.
  4. What business process or problem the code solves is not always self-evident.

In short, you can't write non-trivial code in such a way that it is always completely self-describing. Part of your job is to insure that the fellow coming after you doesn't require a year to figure out your code, and for that, good documentation is a necessity.

  • While I like your answer, let me play devil's advocate for a moment. Comments are not the only way to document code. And some would argue that code comments are not the proper place for documenting things like architecture and design decisions. Using comments for that purpose can make both the code and the documentation more of a burden to read, and render both less effective. – Eric King Nov 7 '16 at 14:55
  • @EricKing: I would expect class comments to include information like "what this is," "why it exists," "suggested usage," and potentially a brief statement about how it integrates into the rest of the system. Such information could be incorporated in a short paragraph or two, and is concentrated in one place, above the class (outside of the code). – Robert Harvey Nov 7 '16 at 16:49
  • I can go along with that. I just prefer it when people don't conflate "comments" with "documentation". Not all comments are documentation, and not all documentation should be comments. Indeed, much of the criticism about code comments that I see is centered around non-documenting code comments. – Eric King Nov 7 '16 at 17:09
  • The code should clearly show how something is done. It may be useful to comment why it was done that way, or to warn why it was not done some other way. – mickeyf Nov 16 '16 at 19:56
4

Sometimes you can write readable code that still requires some additional explanation. Usually these answer the why questions or warn against security or other types of issues that may not be obvious. For example, I wrote a comment last week explaining that a call to glob.glob previous to a call to subprocess.check_call was to avoid specifying shell=True, which is a security risk.

Without that, a future maintainer might just think I made it unnecessarily complex. They would refactor it out, then the check_call would fail. They would go to the docs, find out they need shell=True, and hopefully see the big red warning there. So at best, my comment saved a future maintainer some time. At worst, it saved an accidental security hole.

Note however that it is saying something that I can remember the last comment I wrote. These situations are not particularly frequent.

  • Very good example of what comments SHOULD be for. – John R. Strohm Nov 7 '16 at 15:57
0

Going through this http://www.doxygen.nl/index.html , may help you.

Documentation is necessary, but commenting for each and every variable, for loop, code part is not necessary. Describing what the function does, acceptable inputs and expected type of o/p etc. at the time of declaration, describing the overall functionality of a file, the real-world entity it is simulating etc. is helpful. This helps future programmers to write maintainable code.

But the names of the functions, files, variables etc. should be self descriptive. This helps reader of the program, as people who have not experienced the aftermaths, tend to ignore statements which are not executable. Also, readers are if in hurry, usually don't want to read extra stuff. Basic example - in case of multiple possible values of a variable, which need to be handled in different manners, using a switch-case statement will describe it better than using a chain of if-elseif-else. In later case, you may find a need to give a comment, in former case the code is describing the idea behind it.

In places where, names and coding style don't describe the code in good manner and using alternate coding style may affect performance, you can use comments.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.