Documentation: link from The Insider
-
Just got the email, and it's good to see someone else thinks like I do:http://zachholman.com/posts/documentation/[^] Documentation is worth doing. Provided it's done to help, rather than as an afterthought to pad out the file. I used to hate documentation - it's dull, tedious and never gets looked at. And yes, sometimes that is true. But now I'm older, I document code as I go. I have "XML Commenting" turned on, and "Warnings as errors": I cannot test my code unless I have commented it, because I know I won't find the time to go back and do it later. Does it help? Yes - I find it does. If nothing else, this level of documentation lets Intellisense work with my code. Do you document your code? Or just leave it until the end and hope you'll get moved to a new project before you have to do it?
Real men don't use instructions. They are only the manufacturers opinion on how to put the thing together. Manfred R. Bihy: "Looks as if OP is learning resistant."
When punched cards ruled the Earth and FORTRAN was the language of choice, I learned my lesson about the need to comment programs, even when it hurts. I had been used to programming in BASIC where I could put a comment on the same line as the instruction. With FORTRAN not being able to handle comments except on a separate line, I could never decided whether to put the comments before or after the instruction ("This is what I am going to do" vs. "This is what I just did."). So I fell out of the habit of adding comments to my code. My lesson was learned when I had three card boxes of programs named "TEST1", "TEST2", etc. and I couldn't determine the function of the program by reading the code alone. I ended up throwing out a couple years of programming because of that. At one company I was doing S/370 Assembly programming and the other programmers would tell me it was a waste of time to comment your code. You should be able to determine what it was doing by just reading the code. Having learned my lesson with FORTRAN, I just smiled and waited for the day they needed to do maintenance on their programs. A year later I was rewarded by watching the quizzical and incredulous expressions of those programmers trying to read their own code to figure out where to make their edits. Code tells the machine what to do. Comments tell you why. Back in the day of Apple II's, I used to reverse engineer machine code. I have boxes of paper printouts that I added comments to explain what the program was doing. When I was teaching career changing immigrants how to program in VB6, my suggestion was that you should be able to lay a sheet of paper on the left side of your programs and by reading the comments on the right, you should have your internal documentation. For external documentation, back in the days of working in FORTH, I would write a comment block when I defined the verb and then I had another program that would read the source code to extract the definition line and the comment block to assemble a dictionary of available commands and how to use them. Nowadays I put the "care and feeding" documentation for a program in a MS OneNote file and share it with the other programmers in my team. Since I am old school, I still make printouts and make notations on them of what edits to make. If I find myself writing a line of code interpretation, I make sure that comment gets added back into the source code. Why figure it out again later? User documentation, I generally leave to professional writers. Eng
-
When punched cards ruled the Earth and FORTRAN was the language of choice, I learned my lesson about the need to comment programs, even when it hurts. I had been used to programming in BASIC where I could put a comment on the same line as the instruction. With FORTRAN not being able to handle comments except on a separate line, I could never decided whether to put the comments before or after the instruction ("This is what I am going to do" vs. "This is what I just did."). So I fell out of the habit of adding comments to my code. My lesson was learned when I had three card boxes of programs named "TEST1", "TEST2", etc. and I couldn't determine the function of the program by reading the code alone. I ended up throwing out a couple years of programming because of that. At one company I was doing S/370 Assembly programming and the other programmers would tell me it was a waste of time to comment your code. You should be able to determine what it was doing by just reading the code. Having learned my lesson with FORTRAN, I just smiled and waited for the day they needed to do maintenance on their programs. A year later I was rewarded by watching the quizzical and incredulous expressions of those programmers trying to read their own code to figure out where to make their edits. Code tells the machine what to do. Comments tell you why. Back in the day of Apple II's, I used to reverse engineer machine code. I have boxes of paper printouts that I added comments to explain what the program was doing. When I was teaching career changing immigrants how to program in VB6, my suggestion was that you should be able to lay a sheet of paper on the left side of your programs and by reading the comments on the right, you should have your internal documentation. For external documentation, back in the days of working in FORTH, I would write a comment block when I defined the verb and then I had another program that would read the source code to extract the definition line and the comment block to assemble a dictionary of available commands and how to use them. Nowadays I put the "care and feeding" documentation for a program in a MS OneNote file and share it with the other programmers in my team. Since I am old school, I still make printouts and make notations on them of what edits to make. If I find myself writing a line of code interpretation, I make sure that comment gets added back into the source code. Why figure it out again later? User documentation, I generally leave to professional writers. Eng
FORTRAN was my second language - they taught us COBOL first, probably to scare as many of us off the course as possible - I had forgotten Column 1 'C' is a comment! Weren't punch cards fun? Especially when you dropped them...
Real men don't use instructions. They are only the manufacturers opinion on how to put the thing together. Manfred R. Bihy: "Looks as if OP is learning resistant."
-
Just got the email, and it's good to see someone else thinks like I do:http://zachholman.com/posts/documentation/[^] Documentation is worth doing. Provided it's done to help, rather than as an afterthought to pad out the file. I used to hate documentation - it's dull, tedious and never gets looked at. And yes, sometimes that is true. But now I'm older, I document code as I go. I have "XML Commenting" turned on, and "Warnings as errors": I cannot test my code unless I have commented it, because I know I won't find the time to go back and do it later. Does it help? Yes - I find it does. If nothing else, this level of documentation lets Intellisense work with my code. Do you document your code? Or just leave it until the end and hope you'll get moved to a new project before you have to do it?
Real men don't use instructions. They are only the manufacturers opinion on how to put the thing together. Manfred R. Bihy: "Looks as if OP is learning resistant."
I don't comment my code. It was hard to write so it should be hard to read :laugh: Seriously though. I think it helps in some cases. Especially the things where you have to think hard, like "how the heck would I calculate x? or get value y?". However, I usually make what I am supposed to make and comment it at the end, when I know it does actually work ;) At work things are a bit different... My boss just wants to see green. Today I was forced to place the comment "this is an enum created by our company"... Simply pressing F12 (go to definition) wouldn't do. Supposedly the next person that would maintain the code would not understand that :doh: Looking at his code reveals stuff like:
Select Case obj.GetType
'* SOMETYPE1 *
Case SomeType1'* SOMETYPE2 *
Case SomeType2'...
'* SOMETYPE6 *
Case SomeType6
' Do very difficult stuff here with no comment whatsoever.'...
' If the type is none of the above
Case ElseEnd Select
And the worst part is that the Function that contained the code was recursive, when the type of the Object was of a certain type then for some reason he gets a list of all running assemblies, does some stuff with it, asks for calling assembly, difficult stuff... And none of it is commented!!! :confused: Really, it is comments like that that really make me never want to write another comment again X|
It's an OO world.
-
Just got the email, and it's good to see someone else thinks like I do:http://zachholman.com/posts/documentation/[^] Documentation is worth doing. Provided it's done to help, rather than as an afterthought to pad out the file. I used to hate documentation - it's dull, tedious and never gets looked at. And yes, sometimes that is true. But now I'm older, I document code as I go. I have "XML Commenting" turned on, and "Warnings as errors": I cannot test my code unless I have commented it, because I know I won't find the time to go back and do it later. Does it help? Yes - I find it does. If nothing else, this level of documentation lets Intellisense work with my code. Do you document your code? Or just leave it until the end and hope you'll get moved to a new project before you have to do it?
Real men don't use instructions. They are only the manufacturers opinion on how to put the thing together. Manfred R. Bihy: "Looks as if OP is learning resistant."
That mostly depends on the language I'm using and the purpose I use it for. When I hack something together recreationally in Ruby, I rarely ever comment it (I wrote a maze generator and displayer not so long ago, the only comment in the whole 3-file code is "# First-depth search algorithm") [~400 lines total, all with awesome abstractions that make it possible to generate not only orthogonal but also hexagonal and any other mazes without any adjustments to the generating code whatsoever :D] But when I write C#, I document AT LEAST all public members and functions, also, I never use cryptic function/class/whatever names there (Ruby? Names like "dfs" or "mg" and various instances of "x", "y", "i" and "j" cluttered all over, sometimes overwritten in various scope levels - that said, when I really like what I created, I usually take the time to formalize it a bit, improve and document it. My most polished Ruby product ever was a fully-documented, extensible IRC bot). Also, the short time I was writing Java - full documentation every single time. I'm slightly OCD - if I see there is existing documentation for the existing libraries, I have the need to write similar documentation to my own stuff (while Ruby DOES have pretty thorough documentation, it doesn't rub it in my face as much as C#/VS or Java/Eclipse with it's intellisense). Still - sometimes I enter programming trance mode. In that case, disregard everything I wrote so far and expect swaths of unreadable, over-abstracted code that mysteriously works (or not).
-
OriginalGriff wrote:
Do you document your code?
Yes, every single member (including private members) and code blocks. If nothing, it helps the next person who may end up maintaining your code.
OriginalGriff wrote:
I have "XML Commenting" turned on, and "Warnings as errors":
Good man. :thumbsup: Me too. /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
Ravi Bhavnani wrote:
If nothing, it helps the next person who may end up maintaining your code.
And this next person may actually be you after 6 months.
-
Ravi Bhavnani wrote:
If nothing, it helps the next person who may end up maintaining your code.
And this next person may actually be you after 6 months.
Absolutely! /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
Just got the email, and it's good to see someone else thinks like I do:http://zachholman.com/posts/documentation/[^] Documentation is worth doing. Provided it's done to help, rather than as an afterthought to pad out the file. I used to hate documentation - it's dull, tedious and never gets looked at. And yes, sometimes that is true. But now I'm older, I document code as I go. I have "XML Commenting" turned on, and "Warnings as errors": I cannot test my code unless I have commented it, because I know I won't find the time to go back and do it later. Does it help? Yes - I find it does. If nothing else, this level of documentation lets Intellisense work with my code. Do you document your code? Or just leave it until the end and hope you'll get moved to a new project before you have to do it?
Real men don't use instructions. They are only the manufacturers opinion on how to put the thing together. Manfred R. Bihy: "Looks as if OP is learning resistant."
Documenting your code is equivelant to proof reading your story or letter or whatever you have written that needs to be checked. When you document your code you are forced to examine it as a whole and see it not as indivudal functions/modules/ but as a working whole.
