"Comment everything the right way" and "Instead of writing comments, write more readable code." - Both valid strategies?

Question

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.

Answer 1

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.

Answer 2

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.

Answer 3

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.