I also heard how important documentation is, but after working professionally, I realized not many codebases are extensively documented because most companies prioritize speed. Teams seem to prefer to utilize types and comprehensive tests rather than spending time on writing long documentation which is hard to maintain as the codebase changes.
Yes indeed! Documentation is not always possible and even in a few cases not feasible as well. But in case of collaboration, if we have to onboard a new member or we have to work on the same feature, the documentation does increase the speed of the development. There are always trade-offs in selecting things we do in a project.
Within my teams, we've been a big fan of Architecture Decision Records (ADRs).
There is also good tooling for their creation / maintenance.
For us it severed two important purposes:
Alignment of the team on changes that require alignment / verification of the work to be done.
What we didn't expect, but what we discovered was new joiners to the team could refer to them to get somewhat of a diary of the events that lead to why the codebase is in its current state.
Maybe doesn't work for all teams, but I would encourage researching it.
Learn something new every day.
- I am a senior software engineer working in industry, teaching and writing on software design, SOLID principles, DDD and TDD.
Location
Buenos Aires
Education
Computer Science Degree at Universidad de Buenos Aires
Yes indeed. Good names do play a role in us understanding the code better. Requirement of documentation might not be required in every case as well. But when there is complex logic in the system, I believe that having documentation is more beneficial.
I work as a staff software engineer at a med tec company. We are mainly programming in C++ but my background is also a functional one (Haskell, OCaml).
In the past I did research in program analysis.
I only partly agree to this.
For me the crucial part of documentation is why it has been implemented in the way it was; if not obvious. That typically cannot be realized with proper names.
Learn something new every day.
- I am a senior software engineer working in industry, teaching and writing on software design, SOLID principles, DDD and TDD.
Location
Buenos Aires
Education
Computer Science Degree at Universidad de Buenos Aires
There are other type of documentation that might not be related to coding directly but rather important, you might have:
Requirement documentation, you might have to work with your product owner, project manager and so to collect and correctly document all the businress requirements
Post Mortem, where the whole team, or the involved parties compiles a document about an important bug or some kind of disaster in production. Collecting what went wrong, what went good, what we learned.
Org. protocols, where depending on your seniority level, you might be the right person to document who is on call and what procedures they must follow in different scenarios.
As of coding documentation, you might have an HTTP API documentation, a doc. about a collection of events in a microsevices architecture or a collection of custom events in a micro front-end architecture.
Yes, indeed there is other documentation not relating to coding directly for a project which has an even bigger role. Even in coding itself, there might have been more points that I might have missed. Thank you for sharing the points.
I also heard how important documentation is, but after working professionally, I realized not many codebases are extensively documented because most companies prioritize speed. Teams seem to prefer to utilize types and comprehensive tests rather than spending time on writing long documentation which is hard to maintain as the codebase changes.
Yes indeed! Documentation is not always possible and even in a few cases not feasible as well. But in case of collaboration, if we have to onboard a new member or we have to work on the same feature, the documentation does increase the speed of the development. There are always trade-offs in selecting things we do in a project.
Agreed, even a little documentation is always better than no documentation
Within my teams, we've been a big fan of Architecture Decision Records (ADRs).
There is also good tooling for their creation / maintenance.
For us it severed two important purposes:
Maybe doesn't work for all teams, but I would encourage researching it.
Documentation is the failure to use good explanatory names. IMHO
Yes indeed. Good names do play a role in us understanding the code better. Requirement of documentation might not be required in every case as well. But when there is complex logic in the system, I believe that having documentation is more beneficial.
I only partly agree to this.
For me the crucial part of documentation is why it has been implemented in the way it was; if not obvious. That typically cannot be realized with proper names.
you implement the documentation and then you never update it
Code never lies. documentation always lie
There are other type of documentation that might not be related to coding directly but rather important, you might have:
As of coding documentation, you might have an HTTP API documentation, a doc. about a collection of events in a microsevices architecture or a collection of custom events in a micro front-end architecture.
Yes, indeed there is other documentation not relating to coding directly for a project which has an even bigger role. Even in coding itself, there might have been more points that I might have missed. Thank you for sharing the points.
Thank you so much 😁
Did i miss something? The function in your example returns a boolean which indicates if the given number is prime or not.
Instead of commenting the obvious, you forgot the important ones. E.g. preconditions like that n must be positive.
Your function will return true for any negative number which is not dividable by 2.
Is the flaw in your
primeNumberfunction intentional?Actually no, Thank you for pointing it out. I had noticed it before but forgot to fix it.
In my country is not exist internship, stay employed or unemployed.