Code Comment Style

The best comment I ever read was huge, multi-paragraph monstrosity at the top of the file. It was written in a casual style and had misspellings. I think it gave an overview of the intent of the file (it was like some Perl script) and then rambled on about how the requirements had mopped him into a corner, and that the code was incomplete and likely buggy.<p>It was shockingly humble and transparent, and yet it seemed to flow from confidence, someone who had lots of experience in systems of all shapes and sizes. It was not signed, but I&#x27;m pretty sure it was by one of three coworkers, each of whom had years and years of experience running servers and networks. Its tone was a refreshing contrast to slick smokescreen recited by your average drone, in meetings and emails in the surrounding corporation.<p>And then there were no more comments. Yet the code was more comfortable to read, after that long intro, than most code I run into. I think it was two things:<p>(1) The author stated the intent. What was the file&#x27;s purpose in life? Every line is easier to take in after you know that.<p>(2) The code was written by a human being, just like you and me. Usually code feels a little stiff, no doubt because the main audience member is a computer. A mild injection of warmth and humanity helps me keep my chin up when I face that daunting first read.<p>Would it have been better if it was more concise, spelled perfectly, and had a few line-by-line comments? Maybe. But it was such a treat I still remember it a decade later.

I love comments at the beginning of files that explain what this component is intended to do and how it fits in the big picture. Documentation seems to be so micro focused that its very hard to understand how a piece of code was intended to be used.<p>The Doxygen trend of just dumping APIs and comments at the start of functions and calling it documentation is horrendous.

&quot;It is well known that I prefer code that has few comments. I code by the principle that good code does not require many comments. Indeed, I have often suggested that every comment represents a failure to make the code self explanatory. I have advised programmers to consider comments as a last resort.&quot;<p><a href="https:&#x2F;&#x2F;blog.cleancoder.com&#x2F;uncle-bob&#x2F;2017&#x2F;02&#x2F;23&#x2F;NecessaryComments.html" rel="nofollow">https:&#x2F;&#x2F;blog.cleancoder.com&#x2F;uncle-bob&#x2F;2017&#x2F;02&#x2F;23&#x2F;NecessaryCo...</a><p>I tend to prefer no comments, but more descriptive methods. There may be occasional exceptions.

One big issue with code comments that hasn&#x27;t been mentioned yet: they tend to run out of sync with the actual code.<p>That is, whenever changes to the program are made, you are now required to also update the comment but a lot of times that last step is skipped. One may ask what&#x27;s worse: the absence of comments or _outdated_ comments that no longer match the code.

You aren&#x27;t writing comments for yourself today. You may not even be writing them for your colleagues today. You&#x27;re writing the comments for someone looking at the code in the future, probably without whatever context is in your head now.<p>Also, the most important than you can document is the <i>why</i> because given enough time, a good enough programmer will be able to figure out the <i>what</i>, regardless of how complex it is. But if you made an unusual decision based on something going on in your head at the time, maybe based on some data or testing you had done, no one will know that unless you write it down. This goes part and parcel with a good commit message, which is another place to write down the <i>why</i>.<p>If you haven&#x27;t had the experience at looking at your own code a year down the line and scratching your head at some piece of it, well you just haven&#x27;t been coding long enough. Good comments and commit messages are like gold at those times.

I&#x27;ve seen so many awful standards in my time when it comes to comments. Most of the time it&#x27;s NIH syndrome, or people who love arbitrary rules. People love to make&#x2F;follow rules, but comments are too nuanced for absolutes.<p>I&#x27;ve seen the following... These are all sins in my eyes.<p><pre><code> &#x2F;&#x2F; This code is the property of Blamo inc. &#x2F;&#x2F; Returns the result return result; &#x2F;&#x2F; The name of the entity public string Name; &#x2F;&#x2F; author: @author &#x2F;&#x2F; Date last changed: DD&#x2F;MM&#x2F;YYYY &#x2F;* &#x2F; public property Name &#x2F; The name of the Entity *&#x2F; public string Name { get; set; } </code></pre> I always try to tell people. DRY also relates to comments.<p>Also if you are going to supply me with badly written inconsistent style guide that was cooked up internally with no references or reasoning. I&#x27;m just going to download a popular one from github, and have all the tooling sorted out-of-the-box. I don&#x27;t negotiate with terrorists or religious nutcases.<p>You need a pretty damn good excuse to deviate from industry standards. Most of the time it is personal preferences and a need to be in control.<p>AKA. I care about standards, I just don&#x27;t care about <i>your</i> standards.

Code commenting is an activity that&#x27;s hard to get <i>just right</i>; it seems there&#x27;s either not enough, or none at all or even worse - too much!<p>I&#x27;ve found the following works really well: when doing something non-obvious then comment it immediately. Otherwise wait to see what arises from the Amigo Review. If the reviewer asks any questions, answer them with comments. Once the reviewer stops asking questions then the code is sufficiently commented.

I worked for a place that had drunk the kool-aid about comments being evil so hard that essentially none were allowed, ever.<p>The reason given was frequently &quot;it distracts the brain when reading the code. It makes reading the code take longer.&quot;<p>I&#x27;m sure whatever effect the very occasional one line comment has on reading speed is negligible.<p>When someone cherry picks something someone said once at a conference and forces it on everyone with dogma, you&#x27;re not going to get good results.

What I have trouble with is high-level comments. I very rarely find myself wanting to add comments to an individual file but very often to an entire sub-system. Comments like &quot;this package has classes related to Foo which is like Bar except Baz. Foos are populated from this location and are used with service Qux&quot;. I struggle to find appropriate places for these kinds of comments.

The most ignorant thing I&#x27;ve heard someone say about comments before is how it&#x27;s the worst thing you can do to code. The idea was that code should always be self explanatory. Let&#x27;s just say I left soon after.

<p><pre><code> &#x2F;&#x2F; I use the syntax for single-line comments &#x2F;&#x2F; even for multi-line comments, &#x2F;&#x2F; so that it&#x27;s easy to temporarily comment out &#x2F;&#x2F; a block of code</code></pre>

It&#x27;s striking how some of the most legendary programmers we know of, all say this one thing: comment your code. And yes, I realize that there are plenty of others who are not crazy about comments. But I&#x27;m pretty comfortable siding with Don Knuth on this one.<p>- Donald Knuth invented an entire system of programming ( <a href="http:&#x2F;&#x2F;www.literateprogramming.com&#x2F;" rel="nofollow">http:&#x2F;&#x2F;www.literateprogramming.com&#x2F;</a> ) just to be able to write better documentation for his code<p>- Jamie Zawinski: &#x27;I always wish people would comment more, ... You’ve got to say in the comment something that’s not there already. ... what is this for? Why would I use it?&#x27;<p>- Brendan Eich: &#x27;It’s at the bigger level, the big monster function or the module boundary, that you need docs. So doc comments or things like them—doc strings. ... There is something to literate programming, especially these integrated tests and doc strings. I’d like to see more of that supported by languages.&#x27;<p>- Dan Ingalls: &#x27;As soon as I have it working, I’ll write some comments. And if I like what I’ve done or it seems like it would be hard to figure out, I’ll write more comments.&#x27;<p>(Quotes from <i>Coders at Work,</i> Peter Seibel)

Remember to say WHY, not what!

&gt; use American English<p>What is the reasoning behind this?

I used to be afraid to comment things because I thought everyone was smarter than me and by commenting what is surely obvious to them, I&#x27;m revealing how incompetent I really am.

Idea: every comment should have an assert attached to it. If after a code change assert becomes false, your IDE warns you and you must rewrite the attached comment.

# Markdown Literary programming that don&#x27;t break the syntax of any programming language [1]<p>## Comment Area Markup Method<p>Literary Programming, Programming was the first, Literary was the second.<p>the main purpose of the Code comment area markup method is to live Preview directly in the Code Editor Preview panel without exporting or any preprocessing.<p><i>Just add a line comment character of the programming language before each line of Markdown.</i><p>In the comments of code, you can draw flowcharts,tasklist, display data visualizations, etc.<p>The method is to add extension instructions in any programming language comment area:<p>- markdown<p>- manual eval code, live eval code, print result, display data visualization and other directives<p>When previewing or converting a format, you only need to simply preprocess: delete line comment characters with regular expressions, example: `sed &#x27;s&#x2F;^;&#x2F;&#x2F;&#x27; x.clj`<p>Note:<p>- line comment character of Clojure(Lisp) is `;`<p>- line comment characters of the current file type can be obtained from the editor&#x27;s API.<p>when we edit the code, we can preview the effect in real time. Editing literary code has a live preview panel like most markdown editors.<p>## Advantages<p>- fast, live, simple, no interference.<p>- It don&#x27;t break the syntax of any programming language, you can compile directly. comment area markup method can be applied to any programming language and any markup (including Org,rst, asciidoc, etc.), which is the greatest advantage.<p>- you only need a single line code to delete line comment characters using regular expressions, then you can use any Markdown parse or converter.<p>- Support any code editor that supports Markdwon Live preview, allowing the source code of any programming language to become rich text in real time. In the code&#x27;s comment area, You can use the markdown to draw flowcharts, tables, task lists, and display images on the live preview panel, enhance the readability of your code.<p>- If you extend the Markdwon tag, you can implement the eval code, print result, display data visualization and other instruction tags, to achieve live programming, live test.<p>- When writing (reading or refactoring) code files, It can modify and live preview directly in the editor without exporting or any preprocessing.<p>- Reliable. Maximum code accuracy is guaranteed, and markup language errors do not affect the code.<p>- It hasn&#x27;t interfere anyone to read the code.Markdown is simple, so if it doesn’t have syntax highlighting,it doesn’t have much effect on writing and reading. And having a gray comment area doesn’t affect reading code, especially for people who don’t understand the markup language.Strict distinction between markdown and code, and gray comment area can reduce the amount of information in the source code file, conducive to reading code.<p>## Disadvantages of traditional literary programming<p>- because traditional literary programming users are mainly technical writers, speakers, technical document Maintainers, Style is the document priority, greatly increase the amount of information in the code, interfere with the code reading, especially for non-literary programming programmers are unfriendly, or even unreadable, so there are very few applications in the field of programming.<p>- not universal, specific programming languages and markup languages.<p>- Requires a complex pre-compiler.<p>- Complex to use and high learning costs.<p>- Not intuitive.<p>Therefore, the method described in this paper, in addition to the document-first genre of traditional literary programming, has innovated a new genre ---- code-first genre, so that literary programming in the field of programming Widely used as possible.<p>[1]<a href="https:&#x2F;&#x2F;github.com&#x2F;linpengcheng&#x2F;PurefunctionPipelineDataflow&#x2F;blob&#x2F;master&#x2F;doc&#x2F;markdown_literary_programming.md" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;linpengcheng&#x2F;PurefunctionPipelineDataflow...</a>