Documentation aaaaarrrrgggggg
-
RedDk wrote:
You don't get paid enough to document code.
I don't get paid anything for writing code, I do it for the fun of it.
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
Mike Hankey wrote:
I don't get paid anything for writing code, I do it for the fun of it.
Right, they pay me to do it for them. Although, most of what they have me doing is SSIS and that's not code. :sigh: There has been some coding fun this week as I have been working with the TFS API.
-
When I first started in the industry, the standard was that documentation was to be completed before the first line of code. Some refer to that method as the waterfall method. Today, you seldom see documentation; or, what little there is seldom reflects the product for which it is written. As a basic rule of thumb, write your documentation for an eight-year-old. (I used to have my daughter do the final edit of my documentation until she was eleven.)
Member 10707677 wrote:
documentation was to be completed before the first line of code
That's just a specification. I've seen a few of those, read them, said "OK here's a better way to do that", and wrote something that actually made sense instead. Where I am now I just keep saying "documentation is out of date as soon as it's published".
-
Why is it that we as programmers hate to document? I document code as I go but I write articles for my site on projects and libraries I create and I suck at it, put off doing it and when I do get down to writing it's a slow tedious process.
New version: WinHeist Version 2.1.0 There's a fine line between crazy and free spirited and it's usually a prescription. I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
For one thing, managers generally don't factor documentation time into coding deadlines, so if you spend time documenting it can look like you aren't getting your "real" work done fast enough. But the larger problem is keeping it up-to-date. You may have time to do the initial documentation, but are you going to have time to update it with every change? What about when another team member ninja-edits the code, are you going to regularly check and make sure the documentation still matches the code? I used to try very hard to have good documentation, but I found it to be hopeless. You end up with outdated documentation, which is often worse than no documentation at all. I don't buy the "code should document itself" argument, but for practical purposes that's where we're at, even if you have documentation you still have to go through the code and make sure the documentation isn't lying to you. Edit: There's one time when documentation should be mandatory: when you are leaving a job. You likely aren't going to be needed to meet a coding deadline during your last two weeks, so spend that time documenting the systems you've been responsible for so the next person has something to go by when they pick up those systems. It's good karma, and that's when documentation is really needed and will get read.
-
My code is self-documenting :D I hate documenting my code (i.e. writing manuals), unless it is to teach others how to use a certain technology (like in my blog or articles). And I'm not particulary bad at it. But I do have a degree in Media and Journalism, so I may not be your average documentor :D
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
}Sander Rossel wrote:
I hate documenting my code
One company I worked for, we had documentors that created the documentation in parallel with us. We'd occasionally upset the documentors when we found we had to change something, but we tried to keep it to a minimum. That worked fairly well. Particularly since English was no longer the primary language for the programmers.
Psychosis at 10 Film at 11 Those who do not remember the past, are doomed to repeat it. Those who do not remember the past, cannot build upon it.
-
Sander Rossel wrote:
I hate documenting my code
One company I worked for, we had documentors that created the documentation in parallel with us. We'd occasionally upset the documentors when we found we had to change something, but we tried to keep it to a minimum. That worked fairly well. Particularly since English was no longer the primary language for the programmers.
Psychosis at 10 Film at 11 Those who do not remember the past, are doomed to repeat it. Those who do not remember the past, cannot build upon it.
-
I really enjoyed it. One case in particular, I had written what I called the "Custom Output Processor" for our database product. I had implemented an RPN style calculator so you could do math before displaying the results on the report. It also had commands for copying fields to the report. It was driven by a table of opcodes and arguments that were interpreted by the code. I had user opcodes like RCL, STO, PRT. I was writing the next generation and wanted to make the processing orthogonal and was merrily adding new opcodes like INP, WRT, etc., and the documentor threw up her hands and declared it unteachable. That caused me to pause and recognize she was correct. I redesigned it replacing all the different user opcodes with MOV and the arguments determined the internal opcode for processing. I was particularly pleased because I made it code compatible with the earlier version. You may have written your processing in the earlier version with RCL and STO, but when you opened them in the newer version, you'd see them converted to MOV with the arguments indicating if you were reading a field, register, or an output field. It really helped having a "non-technical" person commenting on what you were creating. (BTW the database was The Data Factory published by Micro Lab, Inc for the Apple II)
Psychosis at 10 Film at 11 Those who do not remember the past, are doomed to repeat it. Those who do not remember the past, cannot build upon it.
-
I really enjoyed it. One case in particular, I had written what I called the "Custom Output Processor" for our database product. I had implemented an RPN style calculator so you could do math before displaying the results on the report. It also had commands for copying fields to the report. It was driven by a table of opcodes and arguments that were interpreted by the code. I had user opcodes like RCL, STO, PRT. I was writing the next generation and wanted to make the processing orthogonal and was merrily adding new opcodes like INP, WRT, etc., and the documentor threw up her hands and declared it unteachable. That caused me to pause and recognize she was correct. I redesigned it replacing all the different user opcodes with MOV and the arguments determined the internal opcode for processing. I was particularly pleased because I made it code compatible with the earlier version. You may have written your processing in the earlier version with RCL and STO, but when you opened them in the newer version, you'd see them converted to MOV with the arguments indicating if you were reading a field, register, or an output field. It really helped having a "non-technical" person commenting on what you were creating. (BTW the database was The Data Factory published by Micro Lab, Inc for the Apple II)
Psychosis at 10 Film at 11 Those who do not remember the past, are doomed to repeat it. Those who do not remember the past, cannot build upon it.
BrainiacV wrote:
It really helped having a "non-technical" person commenting on what you were creating.
Sounds useful.
BrainiacV wrote:
The Data Factory
Haven't heard of it.
BrainiacV wrote:
Micro Lab, Inc
Haven't heard of it...
BrainiacV wrote:
Apple II
Haven... Oh wait, I know Apple! The Apple II was released about ten years before I was even born (not to make you feel old or anything, I guess I'm just young) ;)
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
} -
BrainiacV wrote:
It really helped having a "non-technical" person commenting on what you were creating.
Sounds useful.
BrainiacV wrote:
The Data Factory
Haven't heard of it.
BrainiacV wrote:
Micro Lab, Inc
Haven't heard of it...
BrainiacV wrote:
Apple II
Haven... Oh wait, I know Apple! The Apple II was released about ten years before I was even born (not to make you feel old or anything, I guess I'm just young) ;)
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
}No offense taken. It was a long time ago, in a ... (wait, are you too young to recognize the reference? :laugh: ) Beseech the God Google for "The Data Factory" "Micro Lab" and you'll find reviews. It was an old flatfile database program. And no, I'm not Bill Passauer, I was hired to clean up his, uh, code and myself and another ended up rewriting it completely. But that's another story.
Psychosis at 10 Film at 11 Those who do not remember the past, are doomed to repeat it. Those who do not remember the past, cannot build upon it.
-
No offense taken. It was a long time ago, in a ... (wait, are you too young to recognize the reference? :laugh: ) Beseech the God Google for "The Data Factory" "Micro Lab" and you'll find reviews. It was an old flatfile database program. And no, I'm not Bill Passauer, I was hired to clean up his, uh, code and myself and another ended up rewriting it completely. But that's another story.
Psychosis at 10 Film at 11 Those who do not remember the past, are doomed to repeat it. Those who do not remember the past, cannot build upon it.
BrainiacV wrote:
It was a long time ago, in a ...
I believe that movie came out in the same year as the Apple II ('77) and it's one of my favourite movies ever :D So I guess there goes my excuse ;p
BrainiacV wrote:
Beseech the God Google for "The Data Factory" "Micro Lab" and you'll find reviews.
I won't actually :wtf:
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
} -
The Documentors - weren't that nasties in Harry Potter?
Life is like a s**t sandwich; the more bread you have, the less s**t you eat.
-
When I first started in the industry, the standard was that documentation was to be completed before the first line of code. Some refer to that method as the waterfall method. Today, you seldom see documentation; or, what little there is seldom reflects the product for which it is written. As a basic rule of thumb, write your documentation for an eight-year-old. (I used to have my daughter do the final edit of my documentation until she was eleven.)
Member 10707677 wrote:
documentation was to be completed before the first line of code. Some refer to that method as the waterfall method.
There seems to be different definitions for that method. Some studies have found the most successful projects used a combination of waterfall and agile methods combined. Waterfall starts with an overall plan and relationships. Those ideas are then documented separately breaking it into more plans and relationships. If you keep going like that you can easily get bogged down. Once you get down to about two-three levels, I can see the benefits of abandoning waterfall at that point and going to agile to get early results of the pieces documented to that point.
-
Member 10707677 wrote:
documentation was to be completed before the first line of code
That's just a specification. I've seen a few of those, read them, said "OK here's a better way to do that", and wrote something that actually made sense instead. Where I am now I just keep saying "documentation is out of date as soon as it's published".
I've once read some self documenting code. I hit a point where I said to myself "that is just plain wrong logic". When I brought it to the attention of my manager, we couldn't change it because it was written per the spec document. I asked to see the spec document. I conceded the code did exactly what the spec said it should. She thought the matter was closed when I added "It's too bad it isn't doing what it is intended to do." We spent another hour going though the code to prove that what I saw in fifteen seconds was true. (fixed by changing "<" to ">" or vice versa)
-
For one thing, managers generally don't factor documentation time into coding deadlines, so if you spend time documenting it can look like you aren't getting your "real" work done fast enough. But the larger problem is keeping it up-to-date. You may have time to do the initial documentation, but are you going to have time to update it with every change? What about when another team member ninja-edits the code, are you going to regularly check and make sure the documentation still matches the code? I used to try very hard to have good documentation, but I found it to be hopeless. You end up with outdated documentation, which is often worse than no documentation at all. I don't buy the "code should document itself" argument, but for practical purposes that's where we're at, even if you have documentation you still have to go through the code and make sure the documentation isn't lying to you. Edit: There's one time when documentation should be mandatory: when you are leaving a job. You likely aren't going to be needed to meet a coding deadline during your last two weeks, so spend that time documenting the systems you've been responsible for so the next person has something to go by when they pick up those systems. It's good karma, and that's when documentation is really needed and will get read.
Sometimes documentation (and programs) takes on a life of its own. I keep running across snippets of code and documentation I wrote forty-plus years ago.
-
I've once read some self documenting code. I hit a point where I said to myself "that is just plain wrong logic". When I brought it to the attention of my manager, we couldn't change it because it was written per the spec document. I asked to see the spec document. I conceded the code did exactly what the spec said it should. She thought the matter was closed when I added "It's too bad it isn't doing what it is intended to do." We spent another hour going though the code to prove that what I saw in fifteen seconds was true. (fixed by changing "<" to ">" or vice versa)
Your mention of self-documenting code reminds me of my university days. One of my professors threatened to fail us if we didn't include comments in the source code. This was in the age when punch cards were still being used, so comments were a nuisance. One of the students turned in a final project with a single comment "RUN PROGRAM" as the first card of the deck. The result, when run, was a listing of the source code with accompaning commentary. Needless to say, he passed.
