{"id":167,"date":"2021-02-08T09:35:12","date_gmt":"2021-02-08T07:35:12","guid":{"rendered":"http:\/\/victorrentea.ro\/blog\/?p=167"},"modified":"2021-02-08T09:43:24","modified_gmt":"2021-02-08T07:43:24","slug":"resurrection-of-the-coding-guidelines-document","status":"publish","type":"post","link":"https:\/\/victorrentea.ro\/blog\/resurrection-of-the-coding-guidelines-document\/","title":{"rendered":"Resurrection of the Coding Guidelines Document"},"content":{"rendered":"
<\/div>

I recently got a lot of ideas from the comments I got to a recent post<\/a><\/strong><\/span> on LinkedIN.<\/p>\n

The purpose of Code Review is learning, not blaming.<\/p><\/blockquote>\n

But I won\u2019t discuss code review nor pair programming today, they both deserve their own articles. Instead, I\u2019d like to talk about the Coding Guidelines Document. Every mid-large team ends up writing such a document sooner or later. It\u2019s a document written by developers for developers<\/strong>. It\u2019s a rare kind of beast, as developers are notoriously reluctant to writing documents. Maybe they refrain from writing documents because they realized how fast documents get obsolete in our branch. This idea was captured in the Agile Manifesto, 2nd item: \u201cWe have come to value Working Software over Comprehensive Documentation\u201d.<\/p>\n

So you might hear them saying that:<\/p>\n

The next minute you finish writing a document about code, that document is already obsolete and should immediately be regarded as an archeology product.<\/p><\/blockquote>\n

That might be the default for detailed code architecture documents and documentation, but having this attitude towards a coding guidelines document will immediately defeat its purpose. The coding guidelines are supposed to represent the target coding style of the team, which all developers in the group follow every time they write code.<\/p>\n

Developers themselves put their best efforts into writing this document. It\u2019s true, the act of writing<\/strong> a coding standards document is extremely gratifying: you get to talk about clean code, design principles, and common issues frequently discussed in code reviews. You might start extracting typical code samples from your codebase, have brainstorms and architecture meetings. Then, after a while, you complete that document, and you email it to everyone. Or even better, you put it somewhere visible, on a wiki, and invite people to help to refine it.<\/p>\n

And there\u2019s when it all stops.<\/p>\n

Two years later, most people on the project aren’t even aware that such a document exists.<\/p>\n

What went wrong? We involved everybody in writing that document; we broadcast it to everyone; perhaps we’re still linking it in any email we regularly send to the team members (like the timesheets reminder email \ud83d\udca1). We even took the time to keep that document in sync with the patterns commonly occurring in code reviews.<\/p>\n

But somehow, everyone simply ignores it after a while.<\/p>\n

What to do? You need a reset.<\/p>\n

Delete. Rewrite.<\/h2>\n

I want you to delete that document and then enjoy rewriting it together<\/strong>. A page with ten rules (\ud83d\udca1) that everyone takes into account is far better than a state-of-the-art 50-pages Clean Code book chapter that no one cares about.<\/p>\n

So every 6-12 months, delete it and start anew!<\/p>\n

Tell everyone in the team<\/strong> to write down 5-10 things they would like to see in the Team Coding Guidelines Document and leave them several days to think over.<\/p>\n

Every developer should compile her “personal wish-list of coding guidelines”, because every one of us struggles to master a different set of design goals as she progresses through her career. For sharpening your skills, it’s crucial to try to synthesize these goals in writing, put a name to the issues, and try to describe them in your own words. Plus, the simple fact of writing stuff down tends to make that stuff weigh more for oneself. So push hard: send reminders and insist that every single developer in the team squeezes these bullet points, no excuses.<\/p>\n

You may even put together a little contest: vote for the best topics and offer prizes for the best items or variants. The goal of the Team Coding Guidelines is to find a reasonable common denominator, neither bloated with trivial rules, nor subjective, or too advanced as for a super-senior.<\/p>\n

But again, delete it? Really?<\/p>\n

The team coding habits may have changed since you wrote those guidelines. The very fact that you already had such a document shows a concern that likely helped your developers improve, so they don\u2019t commit the same errors as they were one year ago. Perhaps you realize some rules became useless or evident to everyone. Or maybe you\u2019ve concluded that a particular guideline doesn\u2019t pay off in the long term (example: extract constants from every number in the code). Either way, a rewrite will demand that every rule in there to be strictly needed.<\/p>\n

But more importantly, deleting and rewriting the document anew is so much fun; it\u2019s a joint creative act. Plus, in the end, everyone will be among its authors and signers, and that will feel like a sort of Team Clean Code Manifesto. A joint, well-understood commitment tailored to your codebase and team skill level.<\/p>\n

The Coding Guidelines Document is a Team Code Quality Manifesto.<\/p><\/blockquote>\n

You could cheat a bit and have a quick look at the old document before deleting it, but anything you propose to add to the new guidelines document should be needed today<\/strong>, and you must honestly convince the rest of your team about that. Then archive the old guidelines for historical purposes only.<\/p>\n

Ok, now you’ve (re)written it. What next?<\/p>\n

Adjust in Regular Team Design Meetings<\/h2>\n

Every month sit together with your team and have a chat about every point in this document. Go through all of it in an hour. If it takes longer than that, that’s a sign you should shrink the document or repeat the meeting more often. This meeting doesn’t just allow to continuously adapt and update the rules, but more importantly, offers an opportunity to discuss any tricky design topics.<\/p>\n

The best code happens when you discuss its design with someone else.<\/p><\/blockquote>\n

The simple fact of articulating the design ideas and tradeoffs is crucial to produce simpler, cleaner, and more expressive code. At the same time, hearing your colleagues talk about design is extremely beneficial in terms of learning but also motivating you to do a better job. “If they are talking about it, then it’s important”. But try to make everyone contribute to the discussion if you get to facilitate this meeting.<\/p>\n

Developers are famously reluctant to meetings. They rather spend weeks in code, suffer harsh code reviews, and play “I know better” than sit down in a meeting together. They might actually tell you that they “don’t have time for that”. But that\u2019s crap! Weeks of rework can spend hours of design meetings<\/em> – but make them understand it\u2019s not their private time they spend there.<\/p>\n

Time spent on a coding guidelines document is time earned.<\/p><\/blockquote>\n

Any time spent on constructively brainstorming and fine-tuning the guidelines to follow is by far more time- and stress-efficient than repeatedly arguing about recurring design flaws or painfully reworking the code you’ve put your best effort into writing. These meetings not only help with explaining those rules, but you might get to challenge some of the rules you don\u2019t like.<\/p>\n

On the other hand, you might find out that the vast majority of your colleagues are against one of your personal “best practices”. For example, they might not be so in love with the ternary operator (?:) as you are. Just saying \ud83d\ude09. This social pressure might convince even the most stubborn colleague to adjust his style. \ud83d\udca1<\/p>\n

And slowly, throughout these meetings, your Coding Guidelines Documents will tend to grow indefinitely over years, becoming harder and harder to digest for anyone joining the team. But it\u2019s exactly those new additions to the team that need this document more than any others, to either assimilate or challenge it. Throughout my career as a trainer and consultant, I’ve seen many projects having prohibitively long and complex coding standards documents that no one even dared to open.<\/p>\n

You might try several ideas to shrink it back to a tolerable size:<\/p>\n