--- title: "About maintainable code" url: "https://osherove.com/blog/2003/7/3/about-maintainable-code.md" canonical: "https://osherove.com/blog/2003/7/3/about-maintainable-code.html" published: "2003-07-03T08:35:00" updated: "2003-07-03T08:35:00" tags: ["Off Topic"] author: "Roy Osherove" description: "I'm currently into documenting my source code and creating infrastructure documents. It's amazing how important these things are, I'd say it's inversely related to how boring they are to do J . One of the most important…" usage: "Licensed under CC BY 4.0 — reuse, quote and adapt with attribution (Roy Osherove, link to the original page)." license: "https://creativecommons.org/licenses/by/4.0/" --- # About maintainable code By Roy Osherove July 3, 2003 In [Off Topic](https://osherove.com/blog/category/off-topic) **Historical article** · Originally published July 3, 2003; technical details may be outdated. I'm currently into documenting my source code and creating infrastructure documents. It's amazing how important these things are, I'd say it's inversely related to how boring they are to doJ . One of the most important things I've ever learned about writing code was early in my career. I was a young programmer, entering a new job as a part of a VB dev team. The first few months at that company were one of the most excruciating periods of my career. I literally had to "forget" everything that I thought I knew about writing solid maintainable code , and literally go against my better judgment. The first rule of maintainable code I had to learn: ### Make your code self describing I though I knew it all when I entered that new job. I was right out of another project which, looking back, was one of the worst things I'd ever help create. I really thought I understood the principles of maintainable code: ·         Leave good comments in your code ·         Use Hungarian notation in some pre-agreed format(VB 6) That was about it. I had helped create a coding convention document for VB programmers while I was in my previous job and I was pretty zealous in making people adhere to it. That was before I "got" it. One of the first talks my new team lead gave me included one of the things I would **always tell other programmers not to do**: ·         Try to leave as little comments as you can in your code Jeez! How was I supposed to deal with that? I kept trying to explain to him that writing comments in your code was one of the first tasks I would ever do, that it makes the code maintainable, that without it, the world would be a big pool of chaos and spaghetti code. He would hear none of that. I had to learn the following lessons: ·         **Comments get stale**. If the code changes, the comments need to change too. They usually don't. So what you get is bad explanations - meaning bad maintainability. ·         **If you have to leave a comment to explain what you wanted to do – your code isn’t self describing**. Think about that for a minute. ·         If there really is no other way than to comment, explain **why** something is done, not **what** its doing. ·         If your procedure does not fit into a single screen, its too long. You need to divide work into sub procedures. o        This part was the hard. Sometimes I would show him a procedure, he'd say its too long, and I had to find a way to "artificially" split it into sub-procedures. Once you learn how to do that, you'll never go back. It's addictive – like building LEGO… o        Event handlers should almost always have only one line – which calls a method to do the work. ·         A method's name should explain what it does : InsertCustomer(), CreateSchemaIfNoExists(), FindUserByID()… and so on ·         A variable's name should indicate what type it is(you can also add scope, but that's about the last straw for readability) using partial Hungarian notation. o        I don’t care if VS.NET had built in tooltips to show you a variable's type. I won't always have VS.NET available for code reading. o        This habit comes in **real** handy when printing code for code reviews ·         Boolean methods always start with "Is":  _IsTableEmpty(), IsAnotherLoopRequired(), IsUserInDatabase(), IsPasswordMatching()_ and so on… ·         Putting headers in your modules **is** a good idea, because the overall description of the purpose of a module is likely to never change. This is all just the start of a coding habits manual, but I had the most challenging weeks when I tried to simply write code that adheres to all of them. As I've said – **not** commenting code was one of the hardest to achieve. I've learned, though, that it makes very good sense. ##### _So now I'm documenting my own code_ And I can tell you, following those simple rules sure as hell saves me loads of time today. I am looking at code I wrote more than a year and a half ago, and I understand it pretty quickly, even though the amount of comments is minimal. However I do find some pretty cryptic things here and there. What can I say, I'm human, and I make mistakes. These are usually the things that you get to right at 3am, with a presentation the next day(ah, the life of a startup programmer…). My point – yeah, you have to think a little when writing code, **but** – it totally pays off in the long run (and even immediately), Especially when you're working with a team. I can tell you some pretty horrendous horror stories about bad code, but I'm sure you've all been there. How many of you can tell **goo**d stories of code they received was self-documenting and easy to understand? Is that common ? No. I'd be surprised to hear that it is (I'm not talking about Microsoft, ok?) Heh, I'll just link (again) to my favorite "how to write bad code" article: [How to write unmaintainable code](http://www.mindprod.com/unmain) Update: LondonGeek makes a good comment about how comments that spell the \*intention\* of the code will never get stale.: _"Many programmers don't comment, they annotate their code. For example the say "Create an XML DOM and load it with the text file cust.xml" when they should actually say "Retrieve a list of my customers". The second version enables someone to understand the intent rather than the implementation. This kind of comment will rarely get stale, in-fact it will only get stale when you completely change the intent of the code."_  Agreed, however - why would you need to write that comment in the first place? Why not just make it a method named " RetrieveCustomerList()" which is self describing? He also mentions this great book, which I recommend you have on your shelf - which is filled with great discussion about these kinds of problems: [Code Complete](https://www.amazon.com/exec/obidos/ASIN/1556154844/iserializable-20) [Duncan](http://www.merrioncomputing.com/) points to this link for programming techniques: [http://www.merrioncomputing.com/Programming/7Secrets.htm](http://www.merrioncomputing.com/Programming/7Secrets.htm) ## More in Off Topic [All posts in Off Topic](https://osherove.com/blog/category/off-topic) - Jul 4, 2003 ### [How's this for less eye strain](https://osherove.com/blog/2003/7/4/hows-this-for-less-eye-strain.html) - Jul 4, 2003 ### [I’ve just learned that a friend of mine is looking for a job.](https://osherove.com/blog/2003/7/4/ive-just-learned-that-a-friend-of-mine-is-looking-for-a-job.html) - Jul 2, 2003 ### [Cool Lecture!](https://osherove.com/blog/2003/7/2/cool-lecture.html) - Jul 2, 2003 ### [VB User Group meeting Tonight, Hope to See You There](https://osherove.com/blog/2003/7/2/vb-user-group-meeting-tonight-hope-to-see-you-there.html) --- ## About the author **Roy Osherove**: Senior Solutions Architect at AWS working on AI for production and AI-driven development; author of The Art of Unit Testing and Elastic Leadership, with about 20 years of consulting and training on unit testing, TDD, team leadership and continuous delivery. ### Sites - [RobotPaper](https://robotpaper.ai/): This blog: AI patterns and anti-patterns, AI and coding agents, and engineering leadership. - [osherove.com](https://osherove.com): Roy's personal site. Author of The Art of Unit Testing and Elastic Leadership; consulting and training on unit testing, TDD, team leadership and continuous delivery, plus about 20 years of blog posts. - [The Art of Unit Testing](https://www.artofunittesting.com): The Art of Unit Testing, 3rd Edition (Manning): readable, maintainable, trustworthy unit tests, plus TDD workshops in C#, JavaScript, Java and Kotlin. - [5whys.com](https://www.5whys.com): Roy's writing on software team leadership: self-organizing teams, surviving chaos, learning mode and the Elastic Leadership model. - [Pipeline Driven](https://pipelinedriven.org): Continuous delivery and DevOps practices: build patterns, pipeline-friendly testing, DevOps metrics and enterprise DevOps. - [Elastic Leadership](https://www.elasticleadership.com): Elastic Leadership, Roy's framework for software team leaders (survival, learning and self-organizing modes). ### Social - X: https://x.com/royosherove - LinkedIn: https://www.linkedin.com/in/osherove/ ### Contact - Contact form: https://forms.gle/jQSx5KoXvrVA1JCK7 ### License Licensed under CC BY 4.0 — reuse, quote and adapt with attribution (Roy Osherove, link to the original page). License: https://creativecommons.org/licenses/by/4.0/