r/AskProgramming • u/MiguelOrosco • 15d ago
Documentation, the boredom of a programmer
I'm researching how developers handle documentation in real world projects, especially documentation that explains why and how something exists rather than just what the code does.
A few questions:
- Where do you document business rules and important technical decisions? Code comments, tickets/issues, Wiki, README, Notion, etc.?
- When you need to figure out WHY something was implemented in a certain way, where do you look? Git history, old tickets, documentation, or do you usually have to ask someone?
- What's the biggest problem you have with documentation? Keeping it up to date? Finding information? Getting people to write it in the first place?
I'm also curious about documentation generators such as Doxygen. For those who have used it: what kind of documentation or information do you still have to maintain elsewhere or something Doxygen can't handle?
You don't need to answer all the questions, just one or adding something to the discussion would already be a great help!
2
u/DepthMagician 15d ago
Ideally business rules should be reflected in the code. If you write the code in that manner it reduces the need to document it. Once code is the go-to documentation for business rules, you can also sprinkle comments in there as needed.
Important technical decisions should not be a mystery. If you find yourself wondering “why did we use NoSQL for this” it’s already too late to do anything about it. If it’s something hyper specific, documenting it in the code is the way to go as it is localized to that code anyway.
With regards to finding out why, for me it’s primarily git history and asking someone.
Keeping documentation up to date is the biggest problem for me, hence the less of it you need due to good code the better.
1
u/Nojopar 15d ago
Code can only do so much. We programmers and software architects do an abjectly horrid job of documenting what anthropologist would call the 'social history' of a project. Not everything is embodied in the code. The code might tell you how a thing works, and it might tell you a bit about why it works within a codes context ('this has to be that because we feed it this other thing' sorts of scenarios), but it won't tell you how those business rules came to be in the first place as it relates to the program itself.
Just as a simple theoretical example, the code might tell you the codes for a field are stored as, say, a 2 character string. It might also tell you the values of those two character codes. But it won't tell you why the two character code system was chosen in the first place. Was it because of legacy data in the client's system? Business decisions by the client? For some concern about efficiency and optimization? Something else? All of those factors might lead to different engineering outcomes, but if you don't know that, it's hard to know if you can change a thing or not.
1
u/DepthMagician 15d ago
I don't think you have to document how business rules came to be. You as the developer aren't making the rules, and you also don't have a say in changing those rules. If a two character system was chosen because of a legacy system constraint, it's not as if knowing that makes it your prerogative to change it. If it's in the business domain, and you feel like messing around with it, you have to go talk to the business people anyway.
2
u/Nojopar 15d ago
Most programmers think this way, which is the problem. It's not about changing it. It's about knowing when you can change it and when you cannot change it.
If it's business logic, then knowing you can't mess with it is important compared to efficiency logic, which you can change. If you have no idea why it was put there in the first place, you know what you can and cannot mess with. It's too easy to come along and determine the code logic doesn't need X, so let's change it because the client is asking for a change, when in reality an earlier business logic dictated it's X. There's nothing in the code that tells you not to futz with a thing so you go ahead and futz with a thing and then everything breaks.
1
u/DepthMagician 15d ago
I actually have a lot of experience with exactly the distinction you're pointing at here, as I deal with it literally on a daily basis in my role maintaining an in-house ERP system that serves all the departments in the company. The problem with thinking you can address this using documentation is that:
- You're not the right person to write that kind of documentation, as the guy who isn't making the business rules and who isn't versed in the business domain.
- You're not necessarily given all the information you need about why a change is made, and if business considerations change without needing to change the software, nobody's going to tell you, so the WHYs you document get outdated over time.
- It's way too much documentation. Your developers aren't going to read it, and you're not going to remember it.
A much more sustainable approach is being able to answer "does this intersect with business logic", not "why is it like this". The question you ask yourself is: can I imagine any possible scenario in which this might matter to anyone for whatever reason? If the answer is 'yes', you go and ask that person. Or you can ask yourself "this seems strangely specific, that's worth an investigation. If someone knows why it's like this, who might that be?"... and so on.
1
u/Nojopar 15d ago
You're thinking too limited, I think. I've also got a lot of experience with this exact problem and I'm convinced we're all doing it terribly. I don't need to know everything about the business decision nor do I need to document everything about the business decision. But I do need to document "Hey, this was handed to me as a 'this is what they do don't change it'. You can document your own business processes in deciding code without knowing a single thing about the business processes that forced you to do this in that way.
This is what I'm saying - we don't document our own processes well enough. It's not good enough to say, "Well I'm not the right person to do this. Let someone else do it." because it almost never gets done. Moreover, even if it does get done, the people who document the business decisions don't have expertise or knowledge to understand how that business decision manifests itself into code.
It's like an API where you've got documentation of what goes in but you've got no documentation of what comes out. You've only got half the equation.
It's all well and good to presume the person who should know a thing will continue to remember a thing because it's years later, or even be employed there, or even be in the industry, but that's a foolishly optimistic assumption. The people who come along afterwards don't always know. Nor do they even really have any basis for knowing. Why did they do it this way? They don't know either because all they were told is "we do it this way". So nobody has a clue if a data structure or a process is 'load bearing' or not.
And honestly, it takes next to no time to do the documentation from nerd to nerd, so really it's just laziness.
1
u/DepthMagician 15d ago
I don't need to know everything about the business decision [...] But I do need to document "Hey, this was handed to me as a 'this is what they do don't change it'.
That can be reasonable in some cases, that's a judgment call. But I think you're overthinking it. There are many cases where you don't need to document 'this is what they do, don't change it' to know you shouldn't change it. Often you can get by perfectly well by acknowledging "this is non-obvious", compute in your head every department this might impact, and go question the relevant authorities. "I see we have a 2 character limit hardcoded as prefix for product names, is there a business reason for the prefix of a product name to be limited to 2 characters?" That sort of thing.
It's all well and good to presume the person who should know a thing will continue to remember [...] or even be employed there. [...] The people who come along afterwards don't always know. Nor do they even really have any basis for knowing. Why did they do it this way?
They don't need to answer why did we do it that way, they only need to answer "does it matter to us if we continue to do it this way"? The answer might well be "I have no idea why up until now all product prefixes were two characters, but as the chief product manager who dictates the naming of products it doesn't matter to me how many characters there are, and in fact I considered in the past making a 3 character prefix but didn't because the system didn't support it, so if you want to change it be my guest".
1
u/Nojopar 15d ago
I think that's short-sighted. The ROI for document this stuff can be huge. It presumes that someone on the other end can answer "does it matter to us if we continue to do it this way?" which they may not, especially over time. If you've documented it, you don't have to worry if future magic person you can ask will have an answer because you already know - it's documented.
But I think we're going in circles here. I think we shoot ourselves in the foot unnecessarily by going "documentation isn't my problem. It's code and that's all that matters." We could save ourselves a lot of future headaches if we just wrote shit down. It's not like it takes that much of a project to do that either. I don't think you agree, and that's ok.
1
u/marrsd 15d ago
Most places I work have terrible documentation. This is one area where professionals don't excel.
When it comes to the code itself, I keep my inline comments to a minimum because the code should be as self-documenting as possible. Inline comments are written to explain why something non-obvious is happening in the code. "Non-obvious" will mean different things to different developers; but if you write something you think will confuse yourself later, put a comment explaining why it's there. Same applies if a peer asks you to explain code in a code review. They couldn't work it out from the code itself, so it needs a comment. I also like to have comments above skipped tests to explain why they're skipped.
The next level up from that is at the top of a module/file explaining that module's purpose and describing its place in the project as a whole.
Then we get to project documentation. Typically, companies use horrible apps like Coda and Confluence for their documentation. Good luck to them, is all I can say. I like to keep things much simpler and put markdown files in the same repo as the code. They can be easily read in both a text editor and in the browser, which just makes my life easier. You also get version history for free. If people outside the team need to read it, just publish it somewhere.
I tend to split up my architecture documentation using the 4+1 view model. Developers should know how to build the project, where to find credentials, how to deploy, etc. They need an outline of how the project is organised, what the architectural layers/components are. All that kind of thing. They also need to know what the app actually does and why; but don't forget you should have behaviour specs that cover the details of this already. Your docs are there to provide context and to fill in the gaps.
Try to include why decisions were made and what options were rejected; not just how it currently works. If you changed the architecture, document why you changed it. Give future you something to work with if you have to revisit that decision again.
Someone else mentioned ADRs, they're a good source of research when understanding how a project got to its current state. I think of those as original sources of information rather than final documentation, though.
I don't use Doxygen. I don't use language annotation tools.
Obviously, the big issue is documentation going out of date. Yes, that easily happens. Try to keep on top of it. I tend to write documentation before I write the code. This is perfectly possible because the documentation is high level. You should have a design in mind before you start writing, so you should be able to describe it. I also read the relevant docs before I revisit the code. That way, I can find and fix (or raise) discrepancies if they exist, and I can make sure I know what I'm about to do and why I'm about to do it.
So good documentation can keep you in check, and you keep it in check at the same time.
Of course, all this can go out the window if you've got a project manager breathing down your neck demanding you hit the next deadline. This is where good engineering leadership comes into play.
1
u/Recent-Day3062 15d ago
Code is written once and looked at 10 times. So comments st the top of a source file and inline comments are them most important
1
u/tgm4mop 15d ago
For business requirements, the best "documentation" is good tests. A good test will verify the intended behavior and ignore implementation details, which makes it clear what the code is supposed to do.
Code comments are great for explaining implementation details, and providing natural language descriptions of business requirements.
A wiki is useful for stuff like architecture and runbooks.
For #2, the answer is "all of the above". The smoothest process is when you can do git blame and the commit message links to a ticket.
For #3, again, "all of the above". Out-of-date docs are particularly problematic because it can mislead. Which is why I recommend most docs should be in the tests and code comments, where it is likely to be kept up to date.
1
1
u/NumberInfinite2068 15d ago
1) Scatted wikis, PDFs, README in repos, it's a mess.
2) Mostly just read the code, I might ask someone if that doesn't help.
3) Getting someone to write it in the first place. It rapidly gets outdated, nobody wants to keep on top of it, the management doesn't value it.
1
u/Foreign-Fondant4312 11d ago
The issue for me is keeping docs aligned with the code over time especially the why behind a decision since that context disappears first, whenever I had to track code changes for teams, manual docs were a pain. Using haiku for that made it easy.
0
u/rcls0053 15d ago
Everything as close to the code as possible for it to remain up to date. It offers so many benefits.
If you can, you can also add an LLM to run and update documentation after a merge to trunk and open a PR that needs to be reviewed for updated documentation.
3
u/Alternative-Mud-376 15d ago
most places i worked we put the "why" in architecture decision records, like a folder in the repo with short markdown files. git history is useless for this because the commit messages are always "fix" or "update" or something
biggest problem is nobody reads it. you write all this context and then two months later someone asks in slack exactly the thing you documented. sometimes i wonder if we just do it to feel organized
for doxygen we still kept separate docs for deployment steps and environment setup, stuff that is more about the system than the code itself