Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I remember when I was taught, "comments are the most important part of code." Or rather, when I was told that comments are the most important part of the code. I don't think I was convinced, and I still see common cases where programmers are not convinced of the necessity of good & thorough comments.

I am certainly convinced myself at this point - trying to read, in particular, complex formulae that call functions that call other functions that I don't understand - but I don't know how to convey this to students.

share|improve this question

closed as off topic by Thomas Owens Sep 22 '12 at 13:01

Questions on Programmers Stack Exchange are expected to relate to software development within the scope defined by the community. Consider editing the question or leaving comments for improvement if you believe the question can be reworded to fit within the scope. Read more about reopening questions here.If this question can be reworded to fit the rules in the help center, please edit the question.

add comment

6 Answers

up vote 1 down vote accepted

You've decided you want students to comment, so I won't argue: if, when, how to comment.

Once they can do a coding assignment of some lenth, swap the student's code without them knowing who the original programmer was and ask them to explain what the code does and why. Those who are working with commented code (or self-commenting code if you're into that) will appreciate the difference. Then let them ask the original programmer for explanations. Now they know where they "should" have made a comment. It's not always clear what someone else doesn't understand (And it may be you in the future.).

Also, you're the teacher; deduct from their grade for not commenting. I know they will be better motivated by the why and the inherant benefits to comments when they look at their old code or someone else's, but they're going to work at places with coding standards and possibly code review.

share|improve this answer
add comment

I would NOT insist on commenting practice. The recent trend recommends to skip comments by using self-explanatory naming of variables, methods and functions.

This style of naming by avoiding comments (except very edge cases, where requirements are vague or code logic is prone to changes, or you have a fan of //Todo: style) was new to me couple years ago. However, i found it very helpful while working with team where this guideline was used.

You may essentially wonder why ? Because, using comments would definitely require their maintenance burden. In another words, a programmer may easily forget to update the comments while doing some change in the logic of that method. Thus, your code would be left with obsolete or misleading comment, this is a problem for sure.

So, that is the reason why keeping minimal comments in your code is better in long run.

share|improve this answer
I don't like this style. I have the misfortune of having to work with a lib like that at the moment, where commands are called SECommandsGenerationAndRemoteExecution and stuff, and it really doesn't make for better programs in my opinion. –  Mr Lister Sep 22 '12 at 5:32
There is something wrong in that command/method. "SECommandsGenerationAndRemoteExecution" is violating Single responsibility principle by combining two separate logic and creating dependencies. –  Yusubov Sep 22 '12 at 5:37
I do believe you may have a more preferable way to comment or not to comment, but this doesn't really address motivation even when there may be only edge cases. –  JeffO Sep 22 '12 at 5:52
Code can only tell you how, not why. Selfexplanatory code is not any better at this. –  user1249 Sep 22 '12 at 6:04
+1 to this answer. I had two co-ops start this summer and they are good, hardworking guys who wanted to write "best code possible". Part of that was that school taught them to comment everything and that was something I had to unteach them, much to their surprise. If you write "new A()", No one needs to see a line of comment above it that says "// create an instance of A" It just makes the code that much longer, more to read and more to maintain. Would be nice if school kept up more with industry. –  DXM Sep 22 '12 at 6:27
show 1 more comment

One approach could be to throw your students into a situation where they're likely to wish that they had commented/readable code. You can tell them up-front that the goal is to persuade them of the benefits of readability and commenting by showing them how much more difficult it is to read and understand code when there are no comments at all

For example, providing them with an assignment where they are to take a short, non-trivial program containing no comments whatsoever (and possibly include some deliberate 'bugs' or unnecessary limitations too? e.g. magic numbers without explanation, vague variable/function names etc.), then asking them make to change the program to add functionality and improve its readability; where modifying it requires them fixing the bugs, understanding the original design decisions, how it works, why it works, etc.

You can tell them up-front that one of their goals is to document the code using whatever comments or changes they feel they need to add in order to understand how the code works (Suggesting to them that they can rename things if they feel that is appropriate too). You could then ask for a short individual demonstration from each one of them where they sit down with you and verbally explain to you how it works, what changes they have made and why (using only the code itself including their comments as reference)

Personally I believe this kind of challenge is a good one for university students; since its likely that the first thing they will do when they land a programming job is be thrown into the deep-end of maintaining some rickety old legacy software which is full of bugs, badly named variables and lacking any commenting. Sooner or later, the concept of code readability should hopefully "click" for them.

share|improve this answer
add comment

"Write a lot of comments in your code" is, by itself, stupid advice. Quantity doesn't help; quality does. Comments are one of many tools in your toolbox that you can use to make your code more readable (or less so, if used wrong) - a chainsaw is a wonderful tool for cutting trees, but you shouldn't use it to trim your toenails.

"Write self-explanatory code" is good advice, but just like extraneous commenting, overly explanatory identifier names reduce readability rather than improve on it. You don't want a method signature that reads void ExternalWebsiteUser::UpdatePasswordUsingSHA512HashWithSalt(string passwordDoNotPassEmptyStringBecauseItWillCrashTheApplication) throws DatabaseWriteFailedException, PasswordDoesNotMeetPasswordRequirementsException, ExternalWebsiteUserDoesNotExistException.

The real goal to strive for here is readability, and getting this right takes a lot of experience, especially experience reading other people's code, and having other people review yours.

Assume that whoever reads the code:

  • is fluent in the programming language and its culture (so don't do // increment i by 1)
  • has access to the documentation of any libraries you use (so don't explain usage of third-party libraries in your code)
  • has a rough understanding of the problem domain (so don't jump through hoops describing the entire problem domain)
  • is familiar with common algorithms and design patterns (so don't explain how the Factory Pattern works)

Our goal is to clearly communicate both the what and the why of your code. To achieve this goal, we can use the following devices:

  • consistent and descriptive, yet concise, identifier naming
  • consistent coding style
  • idiomatic code (what the Python community calls "pythonic")
  • code structure that follows the problem domain
  • code that adheres to the Single Responsibility principle
  • KISS, DRY, Single Source Of Truth, etc.
  • formatting
  • comments

From this, it follows that if the other devices are good enough to answer both the "how" and the "why" questions, comments are unnecessary and should be skipped.

Examples of cases where comments are absolutely useful include:

  • Hinting at edge cases and potential pitfalls
  • Giving an overall description of a complex algorithm or formula used somewhere, maybe hinting at resources describing it in detail
  • Defining domain entities in real-world terms when a concise identifier cannot convey the information, even though it has only one responsibility
  • Documenting non-obvious side effects
  • Documenting non-obvious meanings of return values, parameters, etc.
share|improve this answer
add comment

Human by nature is greedy and human by nature is forgetful.

One will only do something when he/she realizes the benefits of it. Therefore, a simple way to make someone to do something is to continuously remind them the benefits of doing that thing. In the case of 'comments' when coding the students need to be continously reminded of how commenting their code will benefits them. Some reasons I can think of are:

  1. Recruiters all the more want to see some code you have written to see your style of coding before they hire you - ( yes they check for comments also )
  2. As these are students, the projects they work on now can help them find a job. So these projects should be well done. Again recruiters see you code for neatness, good architecture and comments so that if you leave tomorrow they can easily maintain the code.

Overall, the main thing is to constantly remind them of the benefits. This strategy not only applies when trying to make students comment their code but works through all aspects of life.

share|improve this answer
add comment

I try to give an answer to the described situation; not to the title question.

In your example, "complex formulae" is more suitably explained in academic-style papers, rather than in-line comments. The steps of code transformations that lead from the formula to the implementation should also be explained in a white paper.

share|improve this answer
add comment

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