Code Commenting Conventions

This is a thread for the discussion of program commenting or documenting conventions, which ofttimes go ignored in programming discussions, including comparing and introducing such conventions, among other subtopics, such as language-specific documentation methods and preferences. Most languages have a means to communicate extra information to the human reader and, as many of the first programs were written in machine code, having no such facilities by way of specification generally solely for machine consumption, many means and conventions of documenting programs in an out-of-band way have come into existence. Common program documentation methods include: comment until the end of the line; delimited comment beginnings and endings; strings as comments; interactive documentation attached to program data; writings after the program end; literate programming; documentation as ignored program information; documentation display as a function of the program; program language constructs specifically designed to communicate information of intent, at times in addition to ease of optimization; and separate manuals. There are many other interesting and useful methods that have not been listed. Feel free to go into detail on your preferred method, methods that you find particularly interesting, elaboration on methods already mentioned, or whatnot. What do you find interesting about program documentation; how do you choose to do so; do you admire or are interested in how, say, a project goes about with this; if given absolute freedom, how would you do this?

I prefer a style that separates a program and its documentation. I find this ofttimes leads to better documentation, as it's no longer constrained to look nice accompanied with the code. It also frees the language or tools from needing to support this, enabling more focus on the actual program. Documentation strings as seen in Common Lisp and other languages are a nice compromise in many ways, and I write them due to their interactive advantage, but this is different from commenting, in many ways, certainly as such is meant for a higher description of the what, rather than the how. So, as an example of what I mean, writing a program and writing an accompanying document or short book seems superior to writing such halfheartedly and worse in conjunction with the program text. The separation of considerations may also generally allow for more reflection than a typical comment is given, since the documentation would probably be written far after a simple comment would. I find it interesting how particularly important machine code programs were previously discussed in length, generally for each instruction or data unit, and included niceties such as flow diagrams and other understanding aids. This is far better than how a machine code program is documented nowadays, certainly, in which a few comments is generally the most given, but this ties in with the lack of handwritten machine code programs nowadays.

I hate comments with a passion, I'm actually considering writing a compiler just to remove support for comments and to throw errors when it sees them. I also hate '--help' options in cli programs, thats what man is for, why have a manpage then embed documentation into the program itself too? Makes me angry. If anything the shell should handle the --help option and interpret "program --help" as literally meaning "man program". It would be cool to have something like ctags though where you can jump from a tag to its documentation in an external file.

>>2579 >>2580 --help is meant as a cheatsheet. As in, "I know how the program works and which options I should pass but I can't recall the exact syntax, please give me a quick reference". You can get that from a man page too, of course, but it usually takes a little longer because there's more text to go through. I don't personally have any particular hate or love for comments. Sometimes you can write code that's self-explanatory, sometimes you just add a small comment to explain what you're doing in a specific fragment and that makes things a lot easier for later maintenance. It's all a matter of what makes the most sense in context, the important part is to have all information needed to understand what's going on in the quickest way possible. Documentation IMHO covers a different use-case, that is it's mostly relevant to explain the usage and expected behavior of code as well as it's broad implementation, whereas comments are more useful to explain details and minutia. This because comments exist right next to the relevant bit of code. tl;dr I think you need both to do things best.

Two things I would like to try are literate programming, and creating a lisp program that is composed of many sub-languages. Both of these would likely result in more readable code than an average say, C++ program. However they aren't exactly applicable to every program so I have yet to come up with a project that would be especially condusive to one of them. Well, I attempted to write a Haskell program "literately" but I was employing a convoluted set of features that I had trouble explaining well, so it didn't really pan out.

>>2580 I hate comments which basically just explain the code in English. A guy I used to work with did that and it turned out to be a big problem because people got lazy and would read the comments INSTEAD OF THE CODE. Which resulted in seriously retarded bugs and general code quality which went unnoticed for years. I think comments are ok only when what you want to say cannot be expressed in code. Otherwise, just read the fuarrrking code.

>>2580 I think that instead of comments everywhere, source code should come with an explanation of how the system is composed at several levels. First, a general layout of what the program does through it's lifetime, separated by the major components Second, a description of how the files map to this architecture And lastly a set of specific descriptions of the independent parts when there are non-obvious aspects, such as specific deadlocks and what components warrant their use. Some projects I've seen do this, but they are the exception by far.

For my next main program, I intend to work in a literate style of sorts, releasing the program, as it's written, in several grouped pieces, with heavy commentary. This is a MIPS program. This is good for me, as it will help me expand my programs and my article. How are you intending to document your next program and why?

>What do you find interesting about program documentation I don't find it particularly interesting, but I do think that good documentation makes or breaks a program. >how do you choose to do so It depends on the size of the project and what documentation exists already. Some things I always do, such as make sure that all of my variables have meaningful names, the code is well-aligned, nothing is difficult to read, and there are enough comments that anyone experienced with the systems my code is working with will be able to read it and understand what's going on. If there's a design document of some sort, I will reference that document along with short exerts or paraphrasings of it. E.g. "This class is ___ following the __ design pattern and interacts with __, __, __, as defined in the design document __." In fact, if there is anything that I reference while writing the code, I make sure to include the reference. If I had to look it up to write it, someone else will need to look it up to understand it. I find that it's also important to have the design docs and supporting material explicitly referenced in the code comments, as it will get people to actually look at those docs before asking you a question, since they don't want to look stupid by asking you a question clearly explained in the design documents. If there's no design documents regarding what I'm writing, I'll comment the code more heavily to convey the design of the program. If it gets to the point where it takes a lot to convey the design behind the code, I'll create a design document. Most of the time, I don't go into writing without some sort of design document, albeit they're usually informal (sketches, whiteboard drawings, etc), because someone else is going to be looking at my code and if they look at a sketch of the design or a flowchart, they can understand the code 10x more quickly than if they read through it themselves. I also prefer to make sure my logic and design is sound before writing a bunch of code and figuring out I fuarrrked it up and need to scrap a lot of it. I make sure my git commits have reasonable descriptions, especially for large changes. If someone says, "it worked until we fixed __", I like to be able to quickly find the commit for it and any notes regarding the changes. >do you admire or are interested in how, say, a project goes about with this OpenBSD has a "the code isn't done until the documentation is done" approach and their man pages and code are absolutely beautiful because of it. >>2580 >I also hate '--help' options in cli programs, thats what man is for, why have a manpage then embed documentation into the program itself too? Makes me angry. Not all systems have man pages. I've been working on a proprietary device that has very limited resources and therefore runs a proprietary distribution of Linux with the man command not installed and no manual files. >>2618 That's a good checklist. Do you have any repos for projects which do this?

I comment and document as much as possible. I go out of my way to write down everything I learned about the problem domain that was necessary to make the program work and I also write down high level descriptions of how my programs are supposed to work from start to finish. I do this because I have ADHD and my attention jumps between wildly different projects frequently; writing my own documentation enables me to quickly review the facts when I come back to a project and resume work much faster. My first goal is to write self-documenting code that is clear enough to be understood without documentation. My second goal is, when the code is too complex for quick understanding, to write comments near it detailing its whys and hows. My third goal is to extensively document the APIs, especially when the project is a library; I document data structures, functions and include usage examples in the documentation as well as in the form of buildable and linkable example code. My fourth goal is to produce separate documents that detail how the software works from a high level point of view as well as how the project is organized so that I or anothee contributor can figure out which part of the codebase should be looked into in order to implement a change. I am a big fan of out-of-band documentation. When I'm researching something, I'll often make notes on simple text files and commit them to the project. I try to keep code comments as terse as possible so that it's still easy to read the code near the comments; external documents have no such constraint.

I like header files because they let you clearly separate interface documentation from implementation documentation, and even when there's little documentation they let you get a quick overview of the exported objects. I wish more languages had adopted them, but most people are likely mentally scarred by them due to C and C++'s "module system" being so terrible.