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.
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.