|
“Programs must be written for people to read, and only incidentally for machines to execute.” - Hal Abelson
Mircea
|
|
|
|
|
Not sure what you mean. 
The difficult we do right away...
...the impossible takes slightly longer.
|
|
|
|
|
Programs without appropriate documentation might as well not exist. They cannot be maintained and, sooner or later, they have to be replaced. Programs with documentation are means to transfer knowledge between people. And yes, they also happen to be executed by computers 
In other words, documentation is critical in my opinion.
Mircea
|
|
|
|
|
I'm working on a much smaller scale project, but it also has this lack of documentation / explanation. It makes it difficult for new team members to get started on it. Documentation would have helped.
Now that you have the knowledge you can create some documentation 
|
|
|
|
|
Sadly there was no or completely infsufficient documentation in the companies I worked for.
Although it is easy to blame the developers, the real culprits I think are management that keeps asking for more bells and whistles instead of allowing time to document things properly.
|
|
|
|
|
Such undocumented code is, unfortunately, more the rule than the exception.
The only thing I can suggest is that as code is modified (maintained / upgraded), you write comments in the code describing what the code does and why. Even a comment header may be useful for those who must follow after you.
I realize that some code bases require that changes be minimal and address only the required change. In that case, you should provide an external document (ensuring that everyone knows where it is), and write your observations in there. This is less ideal that in-place documentation, but will ensure that whatever information you recovered from your colleagues will be there for "future generations".
Freedom is the freedom to say that two plus two make four. If that is granted, all else follows.
-- 6079 Smith W.
|
|
|
|
|
The heck... My initial reply here was for the thread above this one 
Anyway, I am one of those developers who does not write documentation (although I should).
However, what I'd like to see in documentation is:
- Where can I get the code?
- How can I run it locally for debugging purposes?
- How do I commit it to source control (dev branch, merge request, directly on main branch, etc.)?
- How does this application fit in the landscape (is it stand-alone, does it depend on other services, do other services depend on this one)?
- How can I deploy it to various environments (and what environments do we have)?
- Does it depend on any in-house packages and if yes, where can I find those packages and how do I update them?
- Do I need to know about any secrets, passwords, ID's, servers, etc.?
What I'd absolutely NOT want to see in documentation: how does the code work?
Code changes constantly, so I'd have to constantly change the documentation and I'd have to know where I should change the documentation, which is even harder than changing the code.
In code I can check where I use a certain variable, I can't do that in documentation.
So in order to update technical documentation I'd have to very carefully read it every time I change something (and I still wouldn't know if I missed something).
Any documentation I've ever read about code was outdated and did not reflect what the code actually did.
I can follow code using the debugger, so that's its own documentation and never lies to me.
A well-placed comment can work miracles there (like, I have one property that I cannot rename, I have two seemingly separate lines that should be executed in a certain order, and I have a use case for Thread.Sleep).
That said, I now have a client that has a small ASP WebForms layer that only puts records in a database.
The database is then read by some no-code background process.
For starters, I can't know which background process uses which tables without checking ALL background processes (which would take you some hours).
Every process is very hard to follow, has a lot of steps, and A LOT of tables, views and stored procedures.
It's mostly "read the data from some table (or view), send the data to a web API, store the results in yet another table, run a stored procedure that processes those results and puts them in a third table..."
I'm not sure documentation could fix it though 
Documentation should never be a way to fix broken code (or no-code, in this case) or a broken architecture.
Documentation can be really useful for manual processes, like enabling a client or user to use OAuth in your application (if that's a use-case you have, of course).
More like a sort of internal FAQ, what should I do when a customer asks me to...?
That's more functional than technical documentation though.
Documentation has never been a reason for me to join or not join a company.
If a team of six developers can help me with any of the above questions that's almost as good as documentation (until all six decide to quit ).
|
|
|
|
|
Can I respectfully disagree?
First let's clarify what I call "documentation". There is no generic "documentation" but documentation for a certain purpose. To make an analogy with the auto industry, you have the user manual that you get with any new car, than you have a service manual that mechanics use and you have design documentation that stays in the factory. They are not interchangeable and none of them replaces the other ones. You don't want to look at the service manual when you buy a new car and the mechanic has no use for the users' manual (you'd hope he's seen that type of car before). And of course you don't get to see the design documentation that manufacturers guard jealously.
Pretty much the same applies to software. I think the OP was talking about design documentation, or the lack of thereof. It should explain the whys and tell little about the hows. Presumably the purpose of the system and the design don't change that often as to make it constantly obsolete.
What you seem to refer to, is what I call "user manual": how to get the code, where are the passwords and so on. These are the nitty-gritty details that are very helpful but don't explain why the system was designed in a certain way nor how it was implemented.
Finally, for the "service manual", the one that explains how the design comes to life, comments are just perfect. They are right there on the shop floor when the mechanic needs to fix something and can be updated right away when something changes.
Mircea
|
|
|
|
|
It doesn't really sound like you're disagreeing, just explaining things differently, or thinking about other documentation.
We're developers and I assume the documentation Richard is referring to is documentation for us, developers.
I'm also assuming he's not talking about comments in code, because he'd call them comments and not documentation.
Mircea Neacsu wrote: I think the OP was talking about design documentation, or the lack of thereof. It should explain the whys and tell little about the hows. Presumably the purpose of the system and the design don't change that often as to make it constantly obsolete.
That would be my following two points:
- How does this application fit in the landscape (is it stand-alone, does it depend on other services, do other services depend on this one)?
- Does it depend on any in-house packages and if yes, where can I find those packages and how do I update them?
Those two points would also answer Richard's question of "[...] how it works, how the data flows through the different layers and what components do what."
You're a bit more detailed, I think, wanting to know how an application is build in terms of interfaces, base classes, etc. which could be a useful addition if this isn't directly clear from the code.
For example: "For process X we're using IImporters and every client has their own implementation of IImporter which can be found in ... and depends on ... and is chosen/instantiated as follows ..."
Overall, I'm not very concerned with the why of the system.
It's here and people use it for one reason or another, that's a given.
Knowing globally what it does can help in finding and debugging functionality, but it's not a requirement.
That changes when you're tasked with thinking about how to make the program better and more useful for your customers, but that's not usually the task of a programmer and I wouldn't want to find it in the documentation that's supposed to help me run, debug and change a system.
Mircea Neacsu wrote: What you seem to refer to, is what I call "user manual": how to get the code, where are the passwords and so on. These are the nitty-gritty details that are very helpful but don't explain why the system was designed in a certain way nor how it was implemented.
Depends on your point of view.
If a user asks for a user manual, they don't want the code and they're not even allowed to secrets.
A software user manual, to me, would be "to create a new account, find "accounts" in the menu and click on the plus icon ..."
That could be very useful to a developer when a user reports a bug in account creation, but usually you'd ask for steps to reproduce anyway
|
|
|
|
|
I have been considering two alternatives for activities when I retire: Either, I could clean up messy, amateurish Wikipedia articles (maybe even add information, if the article is within my field of expertise. I don't see any possibility of running out of Wikipedia articles that need a cleanup.
Or, I could start working through open source projects, not contributing a single line of code, but adding documentation, from the very top level down to the individual methods, data exchange paths, data structures etc. Or, the intention would be to make neither code extensions or corrections, but I know very well from my documenting my own code (and partially that of others), that it serves perfectly well as rubberducking. When you have to give others a clear and concise description, you discover lots of things that passes by as long as you rush on to implement that new exciting functionality.
I guess that I will stick to Wikipedia. Revealing a messy architecture, inconsistent data structure designs, lack of thread protection where there should be, etc. in a clear and concise manner is bound to lead to a lot of people being upset for me picking on their code. I think that lots of programmers (both of closed and open source code!) fear a view from the outside on their program design. In code reviews, they are used to others reading their conditional statements and loops; that part is OK. But when a system has grown "organically" for five years into a terrible mess of pieces from the method level and upwards, it is rarely subject to a code review. And that is where the problems usually are found. And fixing them requires far more effort than fixes on the code level. No one wants to be told that their architecture and module design have deteriorated into a can of worms.
Well, it rarely is that bad, but most code bases that I have been in touch with have had so many deviations from what was once the original architecture that it negatively affects both reading and maintaining the code. Practically always, I hear "Yes, we know, but ... We hope to get around to clean it up ..." They would not want to have that in writing. They want to pretend that they have gotten that round tuit, even though it isn't the case.
I guess fixing up Wikipedia articles will make fewer people upset.
|
|
|
|
|
It's a curse of knowledge thing.
The user domain and coder knowledge domains don't overlap, so the user thinks they have full documentation WITHIN THEIR DOMAIN (and they probably do), but that's a world away from from it being transferable knowledge and understanding.
Usually, any documentation is some hasty ramshackle bridges from the swampy margins of one domain toward the other, with gaps at the most awkward bits. It's not documented (paved) because almost no one passes that way. It's like finding the old Route 66 (so I'm told).
Have you documented your code (rhetorical..) to a level so that the finance folk could debug it?
|
|
|
|
|
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?
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
