What should NOT be included in comments? (opinion on a dictum by the inventor of Forth)

Posted by AKE on Programmers See other posts from Programmers or by AKE
Published on 2012-10-31T21:56:56Z Indexed on 2012/11/01 11:14 UTC
Read the original article Hit count: 218

Filed under:

coding-style

|

code-quality

|

language-agnostic

|

coding-standards

|

comments

The often provocative Chuck Moore (inventor of the Forth language) gave the following advice (paraphrasing):

"Use comments sparingly. Programs are self-documenting, with a modicum of help from mnemonics. Comments should say WHAT the program is doing, not HOW."

My question:

Should comments say WHY the program is doing what it is doing?

Update: In addition to the answers below, these two provide additional insight.

© Programmers or respective owner

Related posts about coding-style

Which coding style is more common?

as seen on Stack Overflow - Search for 'Stack Overflow'
In no way shape or form am i advertising/promoting my programming style, but as far as 'multiple variable declarations' are concerned, which case is more acceptable professionally and commonly: case 1: private $databaseURL = "localhost" ; private $databaseUName = "root" ; private $databasePWord… >>> More
Java coding style

as seen on Stack Overflow - Search for 'Stack Overflow'
How do you keep yourself coding to standards? There is stylecop and resharper for C#. Are there any tools/eclipse plugins for code analisys in Java? Which of them do you use? >>> More
Is my javascript coding style following best-practice?

as seen on Stack Overflow - Search for 'Stack Overflow'
What is the 'best practise' with regard to coding style. Should I use _ for private members? Should I use this._privateMember? Please re-write my code in proper style if its wrong: (function()){ var _blah = 1; someFunction = function() { alert(_blah); }; someOtherFunction… >>> More
Common coding style for Python?

as seen on Stack Overflow - Search for 'Stack Overflow'
Hi, I'm pretty new to Python, and I want to develop my first serious open source project. I want to ask what is the common coding style for python projects. I'll put also what I'm doing right now. 1.- What is the most widely used column width? (the eternal question) I'm currently sticking to 80… >>> More
Have you changed your coding style recently? It wasn't hard wasn't it?

as seen on Programmers - Search for 'Programmers'
I've used to write code in C-like languages using the Allman style, regarding the position of braces. void foo(int bar) { if(bar) { //... } else return; //... } Now the last two years I have been working mostly in JavaScript and when we adopted jslint as part of our QA process… >>> More

Related posts about code-quality

Tips on a tool to measure code quality?

as seen on Stack Overflow - Search for 'Stack Overflow'
I'm looking for a tool that can provide code quality metrics. For instance it could report very long functions (spaghetti code) very complex classes (which could contain do-it-all code) ... While we're on the (subjective:-) subject of code quality, what other code metrics would you suggest? I'm… >>> More
Everyday Challenges to Improving Brownfield Code Quality

as seen on Code Project - Search for 'Code Project'
How best does one integrate code quality tools into an active project? >>> More
New Extension - Check ADF Code Quality

as seen on Oracle Technology Network - Search for 'Oracle Technology Network'
New free extension available from check for updates >>> More
Why is code quality not popular?

as seen on Stack Overflow - Search for 'Stack Overflow'
I like my code being in order, i.e. properly formatted, readable, designed, tested, checked for bugs, etc. In fact I am fanatic about it. (Maybe even more than fanatic...) But in my experience actions helping code quality are hardly implemented. (By code quality I mean the quality of the code you… >>> More
Counting Lines of code - quality metircs

as seen on Stack Overflow - Search for 'Stack Overflow'
I'm taking the lines of code for my Java project , the project contains lot of XML files too. Now my question is when calculating lines of code. Do i need to consider XML lines of code as well? Please help >>> More