Hello! Tell me where I can look for examples of beautiful design of the program code, its commenting. I wrote my own mini-project, I want to correctly arrange it in order to quickly remember everything after a certain period of time.
the problem with comments, is that they are often not changed when the code is modified. "bad comments are worse that no comments". i find an excessive # of comments makes the code hard to read
i commented a lot when i wrote Fortran, but little when i write C.
ideally, the code is written cleanly and makes its design apparent. meaningful function and variable names are helpful, but local variables should be kept short, single letter. good data structures are better than flow charts
i find adding a comment describing the purpose of a block of code helpful.
comments that clearly describe unusual code can be helpful
5 Likes
Structure, design, and clear intent should (almost) always take precedence. As @gcjr commented, a few phrases intended to illuminate the purpose of large segments of code, and otherwise comment-by-exception, are reasonable. A block of text at the head of the .ino file that describes the overall design and features is also desireable, but keep it high-level.
Also, the use of verbose, informative variable and function names is a far better use of characters, rather than a long text description of a variable or function's purpose.
One caveat - during early development, I find it useful to liberally sprinkle text blocks in the code to keep track of what I'm doing and where I'm going, in case I get interrupted and don't get back to the job right away; that's because I may or may not have yet firmed up the data structures and/or overall design. Nothing worse than coming back to a job a week later and trying to figure out just where you dropped the ball when the "fire alarm" hit. But these comments get expunged as the code gets fleshed out, to avoid becoming "stale" misdirections. When I pick up last year's working code, I expect to find very few comments, and yet be able to pick up and continue developing easily. Others will suggest that this approach isn't necessary, I should design the code before hitting the IDE, but I find that rarely works for me, as I need to 'flesh out' an approach with hands on code.
That's the theory, anyway...
Just a (free) opinion, fwiw.
1 Like
I disagree with that. local variables should be informative as well like global variables. (it's OK and common practice to use i,j or k for for loop indexes if this is what you had in mind for local variables)
2 Likes
are indeed many.
For most code that noobs and near noobs post here, I ignore all comments as they are usually gratuitous
i = i + 1; // add 1 to i
or wrong
delay(200); // delay one second here
The one I LOL are those two that come out of the box with a new sketch
// place code here that runs once
// place code here that runs over and kver
or whatever it is actually. I wrote my own default sketch as soon as I figured out I could.
I usually bump those up to ii and jj and so forth. 
a7
1 Like
2 Likes
I have taken a high speed flight over the first 40 or so pages and deem that document to be worth any time spent on it.
Never too early, but it will make more sense to ppl who have done some coding, and a lot of reading of code, and who may have gotten in deep without any such guidances.
Even if not slavishly adopting all that advice, it is good to at least be exposed to the concept that like any writing, programs can be elegant and readable, that those quailities are worth at least aiming for, as much as the aim is to get the code doing what one wants.
THX for the link.
a7
Commenting is more of an art than a science, so most any rules you can find about how it should be done can be broken when appropriate. If your employer has standards you are required to use, of course, do so.
It's evident from some of the code we see posted here that the programmer was told that every line must have a comment. This is a terrible waste of time and stretches the developer's ingenuity when there's basically nothing to say except echoing the code.
Another standard you'll see sometimes is that every function must have a header comment specifying what it does and what the parameters are. This too smacks of only doing it because you were told to and again, mostly just repeats what you can easily see by reading the code.
The place where comments add value is when they tell you something you can't deduce from the code. Often this is to explain why you're doing something in a particular way, especially if it seems counterintuitive or worse. An explanation that you're doing something apparently pointless because the external hardware requires it can save a lot of head scratching.
3 Likes
yes, variable names defined within a function and in particular an index variable within a loop.
this is the very first thing Kernighan discusses in Practice of Programming. the first chapter is about style.
and in my opinion -- since it's the last book i know of that he wrote -- the book is about getting back to basics
Some might say there are cases where needing to write extensive commentary is a sign that whatever you've done is a bit too clever or out of the ordinary.
That special feeling when one has done something truly creative might should be considered as a warning.
I find comments in my own code
// Sorry, Mom!
and things like
# define SEVEN 8
which are a sign that I've still got some serious lack of discipline. 
In the source code for UNIX I recall seeing a short function that nevertheless had some complexity and tricks and may well have dipped into PDP-11 assembly. A (the only?) comment
/* you are not expected to understand this */
a7
1 Like
ok what he said
By contrast, shorter names suffice for local variables; within a function, n may be
sufficient,npointsis fine, andnumberOfPointsis overkill.
so short but not too short (like n instead of numberOfPoints )
for those interested ➜ https://github.com/memnoth/unix-v6/blob/2c7099ee501923775c4c96079a6fe94da109b552/sys/ken/slp.c#L325
2 Likes
This seems to be relevant to the discussion.
1 Like
i, j, k old FORTRAN hack
Was that written before the '//' comment prefix became in vogue ?
I use lots of comments. Usually I'm the only one who sees my code but it's especially helpful if I come back to the code after a year or so.
Here is a little sketch I wrote as an example or tutorial. It might be "over commented" but I wanted to explain everything because it's a working example of a program that people doing similar projects can start with and expand-on.
Sometimes I'll make-sort-of an outline with comments before I write (or before I finish) the program. Or maybe I'll make a list of functions I'm going to create, etc. Or, sometimes a list at the beginning of the program of things that remain to be done or parts of the code that need to be improved or tested, etc. Of course, those comments can be modified or eliminated once the code is done.
I also like to "label" the curly brackets. I once had a "disaster" with mis-matched brackets in a 5000 line program once after copying and pasting a section of code. The compiler reported hundreds of errors (with unhelpful error messages) and it took me a long time to get back to where the code would compile. If I remember correctly it was just one missing bracket, or maybe one extra bracket.
Oh... I also include an overall description of what the program does, and usually some kind of revision code as I'm "developing" the program. Once the program is done I might just use the date. (But I noticed that the example I linked to above doesn't have a date or any revision information.)
Normally you don't need to comment simple-obvious statements (things that are obvious to someone who knows C++) but sometimes you might want an explanation of why you're doing it or how it relates to to the rest of the code or what you're trying to accomplish.
ctrl t will format and make it easy to spot that same error.
I narrate my thought process as i code. "WHAT" comments are superfluous. "WHY" comments are what counts.
normally the overall structure of my code is language independent.
*title/copyright/prose description
*version history
*constants and structures
*vars
*main code, most probable path straight down, only branchouts for traps.
*Subs and functions in alpha order
any sub function gets a header describing passed and returned vars as well as description
i use visual breaks to show points where control cannot "fall thru". The larger divider, the bigger the break.
By convention, no blank lines means that its easy to mark a "construction zone" by hitting a few blank lines. Close up once unit test passes.
This is what I need! Many thanks!
wow, comments are "a failure to express ourselves in code"
during my early years at Bell Labs, i was sitting with much more experienced developer who said he had seen some code (assembler) with the comment "think about it"
(i think the code modified itself, probably changing a branch op-code from < to >)