|
My first job where I did programming was when I was an engineering liaison for NASA Langley. We never embarked on a large project without first doing all of the documentation. All. It made perfect sense to me, because no person working on writing the code was in the dark about what he was writing and where it fit into the whole, and it left a trail behind for maintenance to use.
Having taken 25 years off to raise children (mostly - I did continue to do web development), I found that this documentation-first idea had been abandoned by the majority of the programming world. I can only assume that it was abandoned for the sake of development speed, and that some creators think that their creativity will suffer from the delay and tedium of creating the documentation. I think it's a bad idea. I mean, I can read code and grep as well as the next guy, but I could have been productive much faster and an expert on the codebase in no time if there'd been documentation, not to mention that the code itself would have likely been more consistent and clean.
jmo
|
|
|
|
|
You haven't heard the "code should be self documenting" crap? I had a manager who wanted comments stripped out precisely because of this.
I will sometimes leave code that has been commented out in just to remind future me, "Oh yeah, we tried that before and it didn't work."
I’ve given up trying to be calm. However, I am open to feeling slightly less agitated.
|
|
|
|
|
For anyone with good knowledge of the language, code is self-documenting, but the document is wildly incomplete, entirely lacking an indexing system (apart from grep which is woefully inadequate), and spread across disparate files in a filing system that is likewise lacking indexing.
I know that part of the appeal of frameworks is to provide some kind of indexing for finding what you need to work on, but frameworks also come with both bloat and inescapable opinions about structure, and not all projects you will come to will be built on one (the one I work on is not, for which I am grateful).
|
|
|
|
|
I once took over a codebase that was in the form of hundreds of UNIX shell scripts in which there was not a single line of comments in any of them. This was exactly at the moment that things were rapidly going to hell in production, and the problem was somewhere in this group of scripts. I reached out to the 'programmer' of the scripts who said that the code itself was the documentation and that (he knew that I was a very good shell programmer) I should be able to figure it out. While it is true that I could unwind the code eventually, we were in a crisis situation where I needed to quickly identify the specific line of code that was causing problems. There was no time for crawling through code, and that is the whole point.
If there is a high urgency, there is no time to 'learn the code'. In that case, a simple, one line sentence at the top of each script--'this script does x'--would have helped enormously. SOME documentation is ALWAYS needed.
Cheers,
Russ
|
|
|
|
|
I agree a lot with what @Sander Rossel[^] and trønderen - Professional Profile[^] had to say. I would add to that that a good high-level architectural diagram can do wonders for quickly learning how the code works. In Psychology, it's called a cognitive map. If a person has a map of the big picture, then it's very easy to fill in the details and know how it all goes together. If you only have the details (the codebase), then you have to create the big picture. If creating knowledge was easier than absorbing it, then school wouldn't exist.
Bond
Keep all things as simple as possible, but no simpler. -said someone, somewhere
|
|
|
|
|
I learned the lesson of good documentation early in my career when I wrote a quick and dirty assembly tool thinking I would only use this once and throw it away. Long story short, 6 weeks later I need to change something and ended up having to spend time reverse engineering my own code. Since that time I have always documented my programming.
Sadly, I can only recount 2 other projects I have done in 35 years that documented anything.
|
|
|
|
|
Quite often, the person who benefits the most from good code documentation is your own future self.
Cheers,
Russ
|
|
|
|
|
That is the absolute truth. Considering how much code costs to develop, you would think more managers would force code documentation standards of some kind. I have not found that to be the case. I had one job where they actually asked that all comments be removed, thinking that this would 'speed' up building the system. Of course, after doing all this work to remove all the comments we discovered that the compiler is very efficient at ignoring them. Who would have thought? Wow?
|
|
|
|
|
I'm going to predict that there is documentation. Most large organizations, and particularly financial ones do create documentation. It's not always great - but it usually exists.
Then the documentation is locked away "need-to-know" for Security reasons, and over time the people who knew, or had access eventually moved on to other things. The documentation is now locked up in a documentation island, imprisoned.
The issue in larger organizations is not that the documentation doesn't exist, it's that at the end of the project it was considered done - and never touched or updated again - and slowly lost as it sunk below the sands. Sometimes a bit of Archeology within the IT organization can dig things up. Try contacting old PM's, the helpdesk, the Architecture team. Usually someone can dig up something.
|
|
|
|
|
|
|
He asks the assistant "Do you have 'European Vespidae Acoustics Volume 2'? I believe it was released this week."
"Certainly," replies the assistant. "Would you like to listen before you buy it?"
"That would be wonderful," says the expert, and puts on a pair of headphones.
He listens for a few moments and says to the assistant, "I'm terribly sorry, but I am the world's leading expert on European wasps and this is not accurate at all. I don't recognize any of those sounds. Are you sure this is the correct recording?"
The assistant checks the turntable, and replies that it is indeed European Vespidae Acoustics Volume 2. The assistant apologizes and lifts the needle onto the next track.
Again the expert listens for a few moments and then says to the assistant, "No, this just can't be right! I've been an expert in this field for 43 years and I still don't recognize any of these sounds."
The assistant apologizes again and lifts the needle to the next track.
The expert throws off the headphones as soon as it starts playing and is fuming with rage.
"This is outrageous false advertising! I am the world's leading expert on European wasps and no European wasp has ever made a sound like the ones on this record!"
The manager of the shop overhears the commotion and walks over.
"What seems to be the problem, sir?"
"This is an outrage! I am the world's leading expert on European wasps. Nobody knows more about them than I do. There is no way in hell that the sounds on that record were made by European wasps!"
The manager glances down and notices the problem instantly.
"I'm terribly sorry, sir. It appears we've been playing you the bee side."
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
*groan*
The most expensive tool is a cheap tool. Gareth Branwyn
JaxCoder.com
|
|
|
|
|
Mike Hankey wrote: *groan*
Seconded! I wonder how many youngins know what the B-side even is?
|
|
|
|
|
And even of those that older records ran at 78rpm?
The most expensive tool is a cheap tool. Gareth Branwyn
JaxCoder.com
|
|
|
|
|
Bring back wax cylinders, that's what I say! 
When I was at Uni, a mate bought his first car - gawd knows how old it was, but it had a starting handle ... and a radio with actual valves in it, so it took about two minutes to warm up before you could hear anything.
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
I think you mean tubes (glass vacuum tubes). They are kind of like a valve.
I think they would blow out like incandescent light bulbs. I remember going to a store with my father to buy a replacement tube for the radio or amp one time.
|
|
|
|
|
They were called "valves" in Right Pond.
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
You could have been tipped off by "lifts the needle onto the next track". Youngsters have no idea what that means, either.
|
|
|
|
|
I remember a elderly faculty member having issues with reading a 5 1/4 inch floppy disk. He tried several times and it wouldn't read. He then called my classmate, who found out that all the while he was inserting it upside down. The student taught the teacher how to insert a floppy disk correctly into its drive.
|
|
|
|
|
Those people who had a Commodore 64 with the 1541 disk drive would know that you could flip the disk over and write to the other side as well. Of course you had to clip a second notch on the side of the disk to allow writing.
Kelly Herald
Software Developer
|
|
|
|
|
Hold still Griff. We're going to have to hurt you now.
Software Zen: delete this;
|
|
|
|
|
My boss gives me "demerits" for bad puns. A shortened version of this one got me 33 1/3 demerits.
|
|
|
|
|
Could have been worse: it might have been a single instead of an LP. Or even worse, a 78! 
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
I'm starting a new job on Monday, and I posed some questions regarding the unit testing stuff they do, and asked this question:
"Which testing framework are we using - mstest, nunit, xunit?"
Response (from one of the testers) - "I'm not sure".
How can that possibly be the case? Should I be worried?
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
