Hi all!
general question: I have to pass my code to another programmer and the source file is more or less 4000
lines. I commented lines and functions in order to describe purpose, input and exit variables.
Is there a standard way/method to document code, or better, to document all the firmware for the
product itself?
Hope my question is clear enough 
Thanks
Some people use a tool named doxygen that generates documentation from comments in the code. It's not magic though, the generated documentation is only as good as the comments the developer wrote. Quite often I find doxygen generated documentation to be of low quality but I have encountered a few projects where it was very good.
I prefer the philosophy of "comments are for programmers, documentation is for users". This means you have a different target audience for each. There's no need to clutter up the source code with a comments that are obvious just from looking at the code and there's no need to force the user to scroll through a bunch of source code just to figure out how to use the project. I like the "documentation driven development" approach. I write the documentation and then do the programming to implement what I documented. The code and the associated documentation are both in the same commit.
Clear and meaningful variable & function names - goes a long way...
Toss a couple of comment lines to explain each modules and function...
What lastchancename said. The first and often only documentation for code is the names that you give the variables, functions, and classes.
I have a little coding standard that I use: any identifier whose value is a physical unit should be suffixed with that union. Thus, periodStart_ms, force_KN, volume_oz.
Comments describe how or why your code works. Documentaiton comments - starting with a /** - describes what someone who just wants to use a function needs to know about it. If your code implements functionality using bogosort, then the fact that bogosort is used, if mentioned at all, goes in a
/* regular comment */
The
/**
* Documentation comment
*/
Describes what the function does and what arguments you invoke it with.
Don't document things that are obvious. For instance in java, this is a no-no
class Foo {
 int bar;
 /**
  Set the value of bar.
  @arg bar the value to which bar will be set.
 */
 public setBar(int bar);
}
Hi guys, thank you all
pert:
I prefer the philosophy of "comments are for programmers, documentation is for users". This means you have a different target audience for each. There's no need to clutter up the source code with a comments that are obvious just from looking at the code and there's no need to force the user to scroll through a bunch of source code just to figure out how to use the project. I like the "documentation driven development" approach. I write the documentation and then do the programming to implement what I documented. The code and the associated documentation are both in the same commit.
+1
...R
I write the documentation and then do the programming to implement what I documented. The code and the associated documentation are both in the same commit.
How often do you find that what you documented isn't what you programmed, and have to revise the document?
PaulS:
How often do you find that what you documented isn't what you programmed, and have to revise the document?
In my case, probably every time. But that does not in any way invalidate the concept.
...R
Those that have used really professional developed equipment have THREE sets of notations.
lastchancename:
Those that have used really professional developed equipment have THREE sets of notations.
- Comments (and internal code explanations)
- Documentation for developers/support/maintenance
(aka Theory of Operation - with explanations of why things are done the way they. are)- User documentation - may be at several levels for admins through ‘users’
When I took the capstone course for my masters degree in computer science, we were to develop a relatively complicated web application that had a variety of users - admins, facilities, professors, and students. We were to include a user's guide for the application. Stunned silence when I asked which users we were to develop THE user's guide for. I submitted 4 user's guides.
PaulS:
How often do you find that what you documented isn't what you programmed, and have to revise the document?
Very rarely. More often I find that documenting what I planned to code makes me look at it from the user's viewpoint too and I end up deciding on a different approach. I had heard of documentation driven development a while back but I still followed the more instinctive workflow of writing code first, then documentation until I started noticing that I would regularly encounter this situation and have to redo the code I just wrote.
I also like that documentation driven development enforces keeping the documentation up to date. It's too easy to write the code and commit without thinking of documentation if you leave it until the end.
It’s a bit like the process of writing your:
Requirements (workflow)
Operating Specifications
It’s no use developing something if it has wishy-washy outcomes that don’t meet a ‘considered’ requirement doc.
There’s a good chance that during testing, you’ll end up some way back near the top to keep the expectations, development, documentation and reliability where you hoped it may end up!
PaulS:
Those that have used really professional developed equipment have THREE sets of notations.
- Comments (and internal code explanations)
- Documentation for developers/support/maintenance
(aka Theory of Operation - with explanations of why things are done the way they. are)- User documentation - may be at several levels for admins through ‘users’
PaulMurrayCbr:
4) Something for management and the executive.
After all, they are the guys that authorize payment of your bill
...R
Since they often have no idea what you’re doing... isn’t that the ‘Requirements’ doc?
—- They’re meant to commission that, and approve it before you ever see the project!
In this case, a personal project... you’re the executive, your other half is the management!
(Since your partner often has no idea what you’re doing... ). 
Don’t worry, if you get it wrong, they’ll let you know!