Self Documenting Code Is Bullshit
Klaus Breyer challenges self-documenting code, advocating for external documentation to enhance precision and abstraction. He emphasizes the need for detailed information like variable units and invariants, promoting a balanced approach for code clarity.
Read original article
The article by Klaus Breyer challenges the notion of self-documenting code in software development. Breyer argues that relying solely on code to explain functionality is insufficient as it lacks precision and abstraction. He emphasizes the importance of documentation outside the codebase to provide essential details like variable units, boundary conditions, and invariants. Breyer suggests a balanced approach where interface documentation focuses on abstractions while implementation documentation delves into specifics. He advocates for central documentation to capture cross-module design decisions comprehensively. Breyer believes that true clarity in code comes from well-placed comments and documentation at appropriate levels. By debunking the myth of self-documenting code, he highlights the necessity of thorough documentation to ensure code understanding and usage.
Related
Documenting Software Architectures
Documenting software architectures is crucial for guiding developers, facilitating communication, and capturing decisions effectively. The arc42 template and C4 model offer structured approaches to achieve this, balancing detail and clarity.
Documentation Driven Development (2022)
Documentation Driven Development (DDD) is proposed as a more effective approach than Test-Driven Development (TDD) for software development. DDD involves starting with documentation to iron out implementation details before coding, helping to address API shifts and scope misunderstandings early on. By documenting requirements and potential future API changes, developers can better plan and refine their code, avoiding costly refactors later. DDD emphasizes the importance of various forms of documentation, including design mockups, API references, and tests, to communicate thoughts and guide development. This method encourages a feedback loop on APIs and work scope, enhancing code quality and project outcomes. DDD aligns with concepts like Behavioral Driven Development (BDD) and Acceptance Test-Driven Development (ATDD), emphasizing user behavior validation and strong communication practices. By incorporating DDD into their workflow, developers can improve collaboration, goal refinement, and code quality, leading to more successful project outcomes.
The software world is destroying itself (2018)
The software development industry faces sustainability challenges like application size growth and performance issues. Emphasizing efficient coding, it urges reevaluation of practices for quality improvement and environmental impact reduction.
The only way to fix a tech zoo is by focusing on stability first
Klaus Breyer stresses stability as key to addressing outdated tech in a step-by-step process. Enhance observability, assess tech objectively, define a vision, and modernize gradually through teamwork and continuous improvement.
Programmers Should Never Trust Anyone, Not Even Themselves
Programmers are warned to stay cautious and skeptical in software development. Abstractions simplify but can fail, requiring verification and testing to mitigate risks and improve coding reliability and skills.
6 commentsDuring the transition, the new development lead said "I'm not going to read the documentation. If the code isn't self-documenting, we're going to rewrite it." Note that he said that not knowing anything about the service they were taking over. Also, it was in a language that had never established strong patterns for itself, so self-documenting when there are no strong patterns is generally meaningless.
Over the next 6 months, he proceeded to ruin the service to the point where it was impacting customers, and got fired for it. In any project of large enough size, self-documenting code falls apart unless you are remarkably good at it. IMO, Go's standard library is an exception to my experience.
That’s not true at all. Good abstractions are methods or classes you can forget the details of and still use effectively. It doesn’t mean you shouldn’t understand them at some point.
If you otherwise have separate documentation that is not generated, if the system/library has any complexity there's a greater chance that documentation doesn't align with implementation and bugs will creep in. That's not to mention stupid developer decisions, such as weird date normalization/structure or similar usage of magic numbers over text keys/flags.
Related
Documenting Software Architectures
Documenting software architectures is crucial for guiding developers, facilitating communication, and capturing decisions effectively. The arc42 template and C4 model offer structured approaches to achieve this, balancing detail and clarity.
Documentation Driven Development (2022)
Documentation Driven Development (DDD) is proposed as a more effective approach than Test-Driven Development (TDD) for software development. DDD involves starting with documentation to iron out implementation details before coding, helping to address API shifts and scope misunderstandings early on. By documenting requirements and potential future API changes, developers can better plan and refine their code, avoiding costly refactors later. DDD emphasizes the importance of various forms of documentation, including design mockups, API references, and tests, to communicate thoughts and guide development. This method encourages a feedback loop on APIs and work scope, enhancing code quality and project outcomes. DDD aligns with concepts like Behavioral Driven Development (BDD) and Acceptance Test-Driven Development (ATDD), emphasizing user behavior validation and strong communication practices. By incorporating DDD into their workflow, developers can improve collaboration, goal refinement, and code quality, leading to more successful project outcomes.
The software world is destroying itself (2018)
The software development industry faces sustainability challenges like application size growth and performance issues. Emphasizing efficient coding, it urges reevaluation of practices for quality improvement and environmental impact reduction.
The only way to fix a tech zoo is by focusing on stability first
Klaus Breyer stresses stability as key to addressing outdated tech in a step-by-step process. Enhance observability, assess tech objectively, define a vision, and modernize gradually through teamwork and continuous improvement.
Programmers Should Never Trust Anyone, Not Even Themselves
Programmers are warned to stay cautious and skeptical in software development. Abstractions simplify but can fail, requiring verification and testing to mitigate risks and improve coding reliability and skills.