• Solutions
    • I Can Help
      • Define
      • Educate
      • Integrate
      • Advise
    • Consultation
      • Assessments
      • Design Reviews
      • Code Inspections
      • Ongoing Support
    • Training Classes
      • Training Schedule
      • On-Site Classes
      • Online Training
      • Customized Coaching and Mob Facilitation
    • Learning Roadmap
      • Developer Essentials Training
        • Agile Analysis and Design Patterns
        • Hands-On: Extreme Programming Practices
      • Scrum Framework Developer Essentials
      • Design Pattern Developer Essentials
      • Object-Oriented Analysis and Design Patterns
      • Scrum Software Developer Essentials
      • Agile Software Developer Essentials
      • Agile Software Developer Intensives
    • Speaking
      • Beyond the Legacy Code Crisis
      • Five Developer Practices for Agile Software
      • Writing High Quality, CLEAN Code
      • Essential Scrum Developer Practices
      • Improving Your Scrum Process
      • The Agile Development Advantage
    • Testimonials
    • Clients
  • Resources
    • Blog
    • My Book: Beyond Legacy Code
    • Bibliography
    • Referral Program
    • Associates
  • Contact
    • Contact Me
    • Schedule A Call
    • About
  • Schedule A Call

Barely Sufficient Documentation

  1. Home
  2. Blog
  3. Barely Sufficient Documentation

2025 Public Training Schedule

June 23 26, 2025 – Agile Analysis and Design Patterns – Half-Day Sessions Online

July 22 – 25, 2025 – Agile Analysis and Design Patterns – Half-Day Sessions Online

Register Now
Or schedule a private class
Course Descriptions
  • Developer Essentials Training
    • Agile Analysis and Design Patterns
    • Hands-On: Extreme Programming Practices
  • Object-Oriented Analysis and Design Patterns
  • Scrum Software Developer Essentials
  • Agile Software Developer Essentials
  • Agile Software Developer Intensives
Follow me on Twitter:

Follow @ToBeAgile

Blog Post Categories
  • Announcements {19}
  • Articles {2}
  • Bits and Pieces {74}
  • Blogosphere {1}
  • Bonuses {2}
  • Build in Small Batches {27}
  • Collaborate {38}
  • Create CLEAN Code {34}
  • Implement the Design Last {11}
  • Integrate Continuously {30}
  • Off-Topic but Interesting {3}
  • Rants {82}
  • Refactor Legacy Code {24}
  • Say What, Why, and for Whom Before How {22}
  • Seven Strategies {38}
  • Specify Behaviors with Tests {17}
  • Write the Test First {27}
Archives
  • 2023
  • November 2023
  • October 2023
  • September 2023
  • August 2023
  • July 2023
  • June 2023
  • May 2023
  • April 2023
  • March 2023
  • February 2023
  • January 2023
  • 2022
  • December 2022
  • November 2022
  • October 2022
  • September 2022
  • August 2022
  • July 2022
  • June 2022
  • May 2022
  • April 2022
  • March 2022
  • February 2022
  • January 2022
  • 2021
  • December 2021
  • November 2021
  • October 2021
  • September 2021
  • August 2021
  • July 2021
  • June 2021
  • May 2021
  • April 2021
  • March 2021
  • February 2021
  • January 2021
  • 2020
  • December 2020
  • November 2020
  • October 2020
  • September 2020
  • August 2020
  • July 2020
  • June 2020
  • May 2020
  • April 2020
  • March 2020
  • February 2020
  • January 2020
  • 2019
  • December 2019
  • November 2019
  • October 2019
  • September 2019
  • August 2019
  • July 2019
  • June 2019
  • May 2019
  • April 2019
  • March 2019
  • February 2019
  • January 2019
  • 2018
  • December 2018
  • November 2018
  • October 2018
  • September 2018
  • August 2018
  • July 2018
  • June 2018
  • May 2018
  • April 2018
  • March 2018
  • February 2018
  • January 2018
  • 2017
  • December 2017
  • November 2017
  • October 2017
  • September 2017
  • August 2017
  • July 2017
  • June 2017
  • May 2017
  • April 2017
  • March 2017
  • February 2017
  • January 2017
  • 2016
  • December 2016
  • November 2016
  • October 2016
  • September 2016
  • August 2016
  • July 2016
  • June 2016
  • May 2016
  • April 2016
  • March 2016
  • February 2016
  • January 2016
  • 2015
  • December 2015
  • November 2015
  • October 2015
  • September 2015
  • August 2015
  • July 2015
  • June 2015
  • May 2015
  • April 2015
  • March 2015
  • February 2015
  • January 2015
  • 2014
  • December 2014
  • November 2014
  • October 2014
  • September 2014
  • August 2014
  • July 2014
  • June 2014
  • May 2014
  • April 2014
  • March 2014
  • February 2014
  • January 2014
  • 2013
  • December 2013
  • November 2013
  • October 2013
  • September 2013
  • August 2013
  • July 2013
  • June 2013
  • May 2013
  • April 2013
  • March 2013
  • February 2013
  • January 2013
  • 2012
  • December 2012
  • Privacy Policy

    (c) 2025 To Be Agile

    • February 7, 2018 ( 1 comments )
    • Bits and Pieces

    In Agile, when we say “barely sufficient documentation,” we’re not referring to user documentation. User documentation has been notoriously bad throughout the entire history of the software industry. As an industry, we must do much better with user documentation than we have in the past, but this post is not about user documentation, it’s about internal documentation. It’s about documenting the design and the code for other developers so that it will be more understandable and easier to work with later.

    There are two important aspects to internal documentation, one of which is often neglected: documentation to express what the code is doing, and documentation to express why the code is doing what it’s doing.

    In traditional software development, we spend an enormous amount of effort documenting what the code does. We do this with design diagrams, specifications documents, and comments in the code. But this kind of documentation can actually become an impediment to maintainability rather than an aide to it.

    The ultimate document that explains exactly what the code is doing is the code itself. Anything else is a distant second and as we write more documents that express what the code does, or pepper our code with comments that express what the code is doing, there is a tendency to make the code itself less expressive. This is a mistake.

    The reason we use programming languages rather than hexadecimal machine instructions to make a computer do something is so that the instructions are understandable to us, the people who write and maintain the code. We have a very different set of concerns than the computer does. The computer isn’t trying to understand the code we write, it simply executes it. But in order for us to change that code, we must understand it. And so we write our software in an intermediate form that’s comprehensible to us and can get compiled down into something the machine can execute.

    If you look at the code that’s generated from our compilers it’s highly efficient. And if highly skilled programmers were willing to sit down for many hours they might be able to write code that’s even more efficient. But efficiency is not our only concern. We’re also concerned with understandability. And if we have to trade some efficiency for greater understandability then it’s often worthwhile to do that.

    As we take these ideas to their logical conclusions, we realize that the bulk of programming is all about communication. Our jobs as programmers is to make our code expressive so that it’s understandable, not just to us but to others as well. And we make code understandable by using metaphors and analogies as well as good intention revealing names to model the domain we’re working in. We should name methods for what they do so the name of the method becomes the most important form of documentation.

    In the past, I have been accused by managers of encouraging developers to write uncommented code and while this is true I have a good reason for it. Software developers don’t like redundancy and if they know they have to write a comment that says what the code was doing, they’ll tend to rely on that comment to communicate the intention of the code rather than the code itself. When this happens the code becomes less expressive and it can be a drudge to read.

    Instead of writing a lot of comments in code, we should find ways of communicating that information with the code itself so our code is more expressive and there’s less need to comment on what the code is doing. However, using block comments to express why the code is doing what it’s doing can often be very helpful and appreciated by the people who maintain the code.

    {1 Comments }

    • Flowy says:
      February 9, 2018 at 9:11 am

      We can take it some levels up:
      -> we can have specification from designers that says what should the code, this can be linked from code so we know who is responsible for what behaviour
      -> we can rewrite these requirements into tests, this way we can be sure the code is doing what it should be
      -> we can make designers to write it in way, they understand it, and also we can reuse it as source for our tests, this can be compiled and executed

      Actually, as somebody said, “comment points to place where developer made mistake”. This is most of time true. Althrought, I’m not saying writing comments is bad, I write them too. When comment is clear and says what the code should do, I take every sentence and convert it into code. This way, code is easily readable, and shorter too. But writing good names and tests is good too.

      Reply

    Previous Post: « Take Your Caller’s Perspective

    Next Post: Why Why »

    Leave a Reply Cancel reply

    Your email address will not be published. Required fields are marked *

    Solutions

    I Can Help
    • Define
    • Educate
    • Integrate
    • Advise

    Consultation
    • Assessments
    • Design Reviews
    • Code Inspections
    • Ongoing Support

    Testimonials Clients

    Resources

    • Blog
    • My Book: Beyond Legacy Code
    • Referral Program
    • Associates


    Read my book!
    Schedule a Call

    Training

    • Training Schedule
    • Learning Roadmap
    • On-Site Classes
    • Online Training
    • Customized Coaching and Mob Facilitation

    Course Descriptions
    • Developer Essentials Training
      • Agile Analysis and Design Patterns
      • Hands-On: Extreme Programming Practices
    • Object-Oriented Analysis and Design Patterns
    • Scrum Software Developer Essentials
    • Agile Software Developer Essentials
    • Agile Software Developer Intensives

    Copyright 2025 © To Be Agile. All rights reserved. Privacy Policy.

    This website uses cookies to improve your experience. I'll assume you're ok with this, but you can opt-out if you wish. Cookie settingsACCEPT
    Privacy & Cookies Policy

    Privacy Overview

    This website uses cookies to improve your experience while you navigate through the website. Out of these cookies, the cookies that are categorized as necessary are stored on your browser as they are essential for the working of basic functionalities of the website. We also use third-party cookies that help us analyze and understand how you use this website. These cookies will be stored in your browser only with your consent. You also have the option to opt-out of these cookies. But opting out of some of these cookies may have an effect on your browsing experience.
    Necessary
    Always Enabled
    Necessary cookies are absolutely essential for the website to function properly. This category only includes cookies that ensures basic functionalities and security features of the website. These cookies do not store any personal information.
    SAVE & ACCEPT