I think that you miss the most is documentation of business process and architecture and why things happen. Documenting it as important. Doing it in exclusively code comments is not.
It is worth only documenting something that does not change often
business rules
business use cases
common user workflows
system integrations and service communications
otherwise documentation feels suffocating and bothersome -> devs will skip it and it quickly becomes outdated, wrong and misleading.
These can't be done in a good way in code -> a separate Wiki is a much better place for that, including features like graphs and links.
For example I recommend plantuml.com/sequence-diagram
Of course it depends on the discipline of your team to keep it updated.
You much easily share your Wiki page with business people of your org and get quick heads up/downs this way - I find it is the best way to check if you have a common understanding of the needed processes.
Hello, thank you for your comments! I appreciate the chance to respond to both in one go.
It appears there might have been a misunderstanding about the message I intended to convey. Practices such as maintaining clean code, following agreements, adhering to internal guidelines, and treating "self-documented code" as a valuable tool are essential for any coders identifying themselves as an engineers.
However, my concern lies with the potential for treating "self-documented code" as a mere ritual, labeling every comment line as boilerplate, and using it as an excuse to bypass the Object-Oriented Analysis and Design (OOA/D) process. I want to emphasize this point. (I am happy if you have never encountered proponents of such "practices", either in real life or online.)
I fully agree with your perspective on the importance of documenting elements that do not change often. Yet, In the codebase, components like Abstract Data Classes or long-standing elements such as "technical debt" objects may remain stable for various reasons.
For instance, "technical debt" objects that persist over time pose a challenge in understanding their role in the overall system, especially for newcomers to the team.
While it is possible (and likely almost needed) to document these aspects outside of the code, it might be viewed as a less-than-ideal practice.
Expecting someone to constantly navigate between the IDE and external documentation, especially in a vast system with numerous interfaces and Abstract Data Types (ADTs), can indeed be a daunting task.
This challenge isn't exclusive to what is typically considered "legacy code" but is a common reality for any system surpassing 300-400k lines of code.
It's all about finding a balance between effective documentation and facilitating a smooth understanding of the codebase for all team members, including newcomers.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I think that you miss the most is documentation of business process and architecture and why things happen. Documenting it as important. Doing it in exclusively code comments is not.
It is worth only documenting something that does not change often
otherwise documentation feels suffocating and bothersome -> devs will skip it and it quickly becomes outdated, wrong and misleading.
These can't be done in a good way in code -> a separate Wiki is a much better place for that, including features like graphs and links.
For example I recommend plantuml.com/sequence-diagram
Of course it depends on the discipline of your team to keep it updated.
You much easily share your Wiki page with business people of your org and get quick heads up/downs this way - I find it is the best way to check if you have a common understanding of the needed processes.
Hello, thank you for your comments! I appreciate the chance to respond to both in one go.
It appears there might have been a misunderstanding about the message I intended to convey. Practices such as maintaining clean code, following agreements, adhering to internal guidelines, and treating "self-documented code" as a valuable tool are essential for any coders identifying themselves as an engineers.
However, my concern lies with the potential for treating "self-documented code" as a mere ritual, labeling every comment line as boilerplate, and using it as an excuse to bypass the Object-Oriented Analysis and Design (OOA/D) process. I want to emphasize this point. (I am happy if you have never encountered proponents of such "practices", either in real life or online.)
I fully agree with your perspective on the importance of documenting elements that do not change often. Yet, In the codebase, components like Abstract Data Classes or long-standing elements such as "technical debt" objects may remain stable for various reasons.
For instance, "technical debt" objects that persist over time pose a challenge in understanding their role in the overall system, especially for newcomers to the team.
While it is possible (and likely almost needed) to document these aspects outside of the code, it might be viewed as a less-than-ideal practice.
Expecting someone to constantly navigate between the IDE and external documentation, especially in a vast system with numerous interfaces and Abstract Data Types (ADTs), can indeed be a daunting task.
This challenge isn't exclusive to what is typically considered "legacy code" but is a common reality for any system surpassing 300-400k lines of code.
It's all about finding a balance between effective documentation and facilitating a smooth understanding of the codebase for all team members, including newcomers.