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."
It is certainly better than the "What the hell was I trying to do here?????" scenarios.
...and I have extensive experience writing computer code, including OIC, BTW, BRB, IMHO, LMAO, ROFL, TTYL.....
-
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."
Totally agree. mff years ago, I started to comment before code and it really does work. You write the comment of what the method or class will do BEFORE you write any code. Then when it's finished, it is easy to just read through and check it is still right rather than trying to describe [badly] what you have done. I started on a project to take a formalised design and produce outline code, but it kept stalling as I had more important things to address.
Panic, Chaos, Destruction. My work here is done. or "Drink. Get drunk. Fall over." - P O'H OK, I will win to day or my name isn't Ethel Crudacre! - DD Ethel Crudacre Have a bit more patience with newbies. Of course some of them act dumb -- they're often *students*, for heaven's sake. -- (Terry Pratchett, alt.fan.pratchett)
-
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."
OriginalGriff wrote:
Do you document your code?
I comment on everything that I feel isn't obvious what it is doing or I know that 3 months down the line I'm wondering what the heck this does and why did I do it that way.
Lobster Thermidor aux crevettes with a Mornay sauce, served in a Provençale manner with shallots and aubergines, garnished with truffle pate, brandy and a fried egg on top and Spam - Monty Python Spam Sketch
-
I comment my code loads, and usually put lots of info into any bugtracking system things are raised in. I don't do much in the way of big documents and diagrams and things usually though in most cases, but it depends on the situation. My pet peeve is auto-generated documentation using things like ghostdoc though, which just adds comments that tell you the blatantly obvious from the method name. Does something with a thingy. public void DoSomething(object thingy) That kind of thing adds no value in my view and neither does an empty summary block.
I almost always edit Ghostdoc generated comments. The benefit of Ghostdoc (imho) is not having to manually type argument names. /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."
your signature tells something different: Real men don't use instructions. They are only the manufacturers opinion on how to put the thing together. I do write before the implementation starts - some software detail documentation (SDD)[^] and some SAD (Software Architecture Documentation). Often enough I do my own timeline and work package planning. Afterwards there's just the code commenting (Java Doc). But I like to limit that to the function headers - the function inside is mostly simple enough to go without further documentation. regards Torsten
I never finish anyth...
-
Totally agree. mff years ago, I started to comment before code and it really does work. You write the comment of what the method or class will do BEFORE you write any code. Then when it's finished, it is easy to just read through and check it is still right rather than trying to describe [badly] what you have done. I started on a project to take a formalised design and produce outline code, but it kept stalling as I had more important things to address.
Panic, Chaos, Destruction. My work here is done. or "Drink. Get drunk. Fall over." - P O'H OK, I will win to day or my name isn't Ethel Crudacre! - DD Ethel Crudacre Have a bit more patience with newbies. Of course some of them act dumb -- they're often *students*, for heaven's sake. -- (Terry Pratchett, alt.fan.pratchett)
Nagy Vilmos wrote:
I started to comment before code and it really does work.
This takes a lot of discipline but forces you to think why you're writing that bit of code (i.e. what are your consumer's needs) and imho leads to better code quality overall. Over the years I've also started writing tests before I implement the body of my methods. /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
Ravi Bhavnani wrote:
Yes, every single member (including private members) and code blocks. If nothing, it helps the next person who may end up maintaining your code.
Agreed: and persuaded the team to do the same: now reject any code that is not commented. (Before some smart-arse says anything I mean commented with something meaningful that pertains to the code).
"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." Red Adair. nils illegitimus carborundum me, me, me
digital man wrote:
Agreed: and persuaded the team to do the same: now reject any code that is not commented. (Before some smart-arse says anything I mean commented with something meaningful that pertains to the code).
Sadly, I have seen many methods whose "Summary" was just the name of the method. :sigh: All done by the near mythical programmer who no longer works for the company. ;)
Just because the code works, it doesn't mean that it is good code.
-
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 know a lot of professionals shun documentation, but I always document code in comments, and when called upon to do work for others, in separate design documents. I've had to maintain a lot of code in decades past, and the comments and design docs are really helpful in interpreting what was probably clear to the original developer, but totally non-obvious to the poor sap who has to maintain it. Now that I progeam almost exclusively for my own use, documentation is even more useful. Typically, I get an idea for an app I need, spend a few furious nights coding after work, hit a block, then run off to do research and, that failing, post a plea for help at CodeProject. Then things happen - work gets horrendously busy, something at the house breaks and needs fixing, the truck needs work, whatever. It can sometimes be months before I get back to my project, and by then I've forgotten what I was thinking at the time. Without extensive comments I'd be lost in my own code, and probably have to start over from scratch. Given that I have, at most, about 10 hours or less per month available for programming activities, I can't afford the time to try to muddle through my previous work to figure out where I was going with it. I suspect that, for a professional programmer, this is equally true when assigned multiple projects that have to be developed concurrently.
Will Rogers never met me.
-
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."
-
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."
-
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 write tons of comments. Comments help me remember when I've done something tricky. Comments are like a conversation with myself. If I can explain a thing, it means I understood it. Comments help me make sure I know what I'm doing. Comments make a visual separation between methods, so I can find things very quickly. Comments augment the code, like telling when a reference or pointer argument is an in/out parameter, something for which C++ does not have a direct implementation concept.
-
Totally agree. mff years ago, I started to comment before code and it really does work. You write the comment of what the method or class will do BEFORE you write any code. Then when it's finished, it is easy to just read through and check it is still right rather than trying to describe [badly] what you have done. I started on a project to take a formalised design and produce outline code, but it kept stalling as I had more important things to address.
Panic, Chaos, Destruction. My work here is done. or "Drink. Get drunk. Fall over." - P O'H OK, I will win to day or my name isn't Ethel Crudacre! - DD Ethel Crudacre Have a bit more patience with newbies. Of course some of them act dumb -- they're often *students*, for heaven's sake. -- (Terry Pratchett, alt.fan.pratchett)
Agreed, with the exception of obvious properties. (If I have to document for someone what the Person.FirstName property is for, one of us needs to find other employment). Nagy's suggestion is good in two ways which I can think of right off: 1) When developing moderately complex logic, testing will often reveal flaws in the original thoughts. Helps you to learn how to think more logically the first time. 2) When developing more complex things, often I'll do a little bit, test it, iterate. If iteration n comes after lunch/break/going home, it's good to have that reminder of "what was I going to next?"
-
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."
Yes. Everything that isn't trivial (i. e. that I need to think about how to best code) I write down in documentation first. Be it the description of an algorithm, some pseudocode, pointing out some nonobvious preconditions, whatever appears useful to later understand whats going on (or is supposed to be). This method helps tremendously to get back into my work when I'm disrupted for days or weeks by whatever reasons. Also, when analyzing foreign code, I often enter my insights into the code as documentation, so others can later benefit from my work (or, more often, I). I sometimes even take the time to reread and confirm (or correct) those comments after I'm done fixing whatever problem there was. ;) If I came into a new project team and were asked to not 'waste time' commenting code I'd be rather unhappy, to say the least. I know how much I benefit from comments and I also know how much more time it takes to get into some code without, even my own. Comments are never 'wasted'. The time writing them clears your head to do better code right from the start. And everytime you come back to that code you'll be much more efficient.
-
I comment my code loads, and usually put lots of info into any bugtracking system things are raised in. I don't do much in the way of big documents and diagrams and things usually though in most cases, but it depends on the situation. My pet peeve is auto-generated documentation using things like ghostdoc though, which just adds comments that tell you the blatantly obvious from the method name. Does something with a thingy. public void DoSomething(object thingy) That kind of thing adds no value in my view and neither does an empty summary block.
You're missing the point. Tools like GhostDoc or Atomineer can save a lot of time doing the most dull and repetitive parts of documentation such as keeping the docs in sync with changes to the code - time that you can spend on better documentation or on writing more code. Auto-generated documentation can't tell you more than the code already "says" - but it can summarise the key points in a more readable form and save a lot of time writing and updating comments. If you don't like the text that is provided, then you're missing the point - that text appeared instantly, and can be incorporated into your own descriptiosn to save you bucketloads of time. These addins are tools, and if used correctly, they can save you thousands of dollars of time a year. To answer the OP, I usually write a description of my class/method and then fill in the implementation to match that "micro design". This is a quick approach that really helps to iron out my assumptions and design ideas by thinking about the code before I write it. And then it acts as documentation for any reader to help them understand the code later. I simply can't write code without writing down an overview of what it will do first. It's much faster overall because I make far fewer mistakes and produce far fewer bugs.
-
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."
Like you, I used to hate documenting my code but back in the bad ole 3GL days my immediate superior used to check our code and if we didn't document he made us go back and put it in. Therefore I got used to doing it. Now I don't even think about it. I document as I go and like you I have found it very useful especially when adding funtionality to and/or going back to debug an application I haven't look at in a while. I would even go as far as saying it should part of best practice.
-
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.
