What are the benefits of using comments

coding-styleprogramming practicesprogramming-languages

I just accepted a new job. Our application is in the 50,000 lines of code area. None of which is commented. I am finding it difficult to understand how the application works. Id like to prevent this for the next person that joins the project by getting the team to start to use comments.

Forget about if you support comments or consider them code duplication. What are some of the benefits of using comments that I can use as reasons for the team to start using them. What arguments are there in favor of comments (Not looking for opposing arguments). Are there any publications or studies done that show that using comments improves code quality or something like that?

Best Answer

Clean Code has a whole chapter on comments, when they're good and when they're not. Also a lot of practical advice on how to write code that doesn't need so many comments.

Edit: Anna asked for a summary, and since you were asking only for pro-comment reasons, the table of contents level summary of good reasons to use comments from the book includes:

Legal notices, like copyrights
When you can't use a function name to explain something
Your intent behind a decision
Clarification of code you can't alter, like library call results
Warning of consequences
TODOs (to a reasonable degree)
Amplify the importance of something seemingly inconsequential
Javadocs in public APIs

There's a couple paragraphs or more on each of those topics, with actual code samples included for illustration. It really is a worthwhile read.

Related Solutions

JavaScript Tips – Switching from ActionScript to JavaScript: Tips for Writing Code

Autocompletion

Javascript is a dynamic language and it's impossible to get anywhere near to what you have in Actionscript or Java. Just accept what your IDE (WebStorm for instance) might suggest for you. This goes for any interpreted language really.

How to organize code?

Have a look at requirejs or node.js's own module require function.

Anonymous functions.

Yes, get use to them. Javascript is very much function-based so you'd just have to accept that part. Here is a great starting point.

Several tags and I declare a variable in one of them, can the tags below it and above it access that variable?

Nope, only tags below it. Try this:

<body>
   <script> console.log(x); </script>
   <script> var x = 1; </script>
</body>

Console prints "x is undefined".

C++ – Non-Optional Pointers vs Non-Const References

The rationale behind Google's style guide is simply to make it clear from a function's call site whether a parameter is an input parameter or an output parameter. (See here for further discussion.) Other languages make out parameters explicit by design; C#, for example, has an out keyword that must be used at the call site. Since C++ doesn't make it explicit, Google chose to use const ref. versus pointer to make it clear.

Is this only a Google rule? No, but I doubt it's very widespread. I don't think I've seen it outside of Google's style guide and groups that explicitly adhere to parts of the Google style guide. (For example, I liked the idea when I first read the Google style guide years ago and have used it for some of my own code.)

In particular, the newly announced C++ Core Guidelines prefer return values to output parameters for (almost) everything and uses non-const refs for the rest. Google's use of pointers versus references might make output parameters clearer, but return values are clearer still. Now that C++11 has standardized moves (rvalue references, &&, to make returns of many types cheap) and tuples (allowing an easy way to return multiple values), many of the use cases for out parameters no longer apply.

The C++ Core Guidelines have some big names (Bjarne Stroustrup, Herb Sutter) behind them, are supported by Microsoft, and embrace the latest C++ features (unlike Google's style guide), so I expect its recommendations to be more popular than Google's.