Next: Some Comment Functions, Up: Comments [Index]
Comments that start with a single semicolon, ‘;’, should all be aligned to the same column on the right of the source code. Such comments usually explain how the code on that line does its job.
Comments that start with two semicolons, ‘=;;=’, should be aligned to the same level of indentation as the code. Such comments usually describe the purpose of the following lines or the state of the program at that point.
We also normally use two semicolons for comments outside functions.
If a function has no documentation string, it should instead have a two-semicolon comment right before the function, explaining what the function does and how to call it properly. Explain precisely what each argument means and how the function interprets its possible values. It is much better to convert such comments to documentation strings, though.
Comments that start with three semicolons, ‘;;;’, should start at the left margin. We use them for comments which should be considered a heading by Outline minor mode. By default, comments starting with at least three semicolons (followed by a single space and a non-whitespace character) are considered headings, while comments starting with two or fewer are not. Historically, triple-semicolon comments have also been used for commenting out lines within a function, but this use is discouraged. When commenting out entire functions, use two semicolons.
Comments that start with four semicolons, ‘;;;;’, should be aligned to the left margin and are used for headings of major sections of a program.