-1

My manager wants us to complete a checklist for a Definition of Done, where the checklist items are short.

What is a good way to phrase "code is clear" that might better imply that the code is understandable by a reasonable software engineer, well-organized and appropriately commented and documented? (If I say that explicitly, it's too long.)

  • 1
    If your manager wants a list, why dont you split code is clear into multiple points? For example, code is understandable, code is well-organized, code is appropriately commented, and code is appropriately documented. – pschill Jul 31 '18 at 17:41
3

If you want code that is understandable by someone else on your team, have someone else on your team review it and say so.

These are called code reviews, and a widely expected part of the Definition of Done.

"Is it organized?"

"Is it commented?"

Then becomes part of your Code Review rubric/guidelines/criteria, which can usually be more flexible over time and per-team.

2

The judgement “the code is clear” is not objectively measurable, and therefore problematic. Instead:

  • If code clarity is important to your team, start doing code reviews (works great with a pull-request based workflow). Your Definition of Done then includes “the code was reviewed”. There is a danger that a code review just rubber-stamps any changes, but that is a separate problem.

  • Use automated style checking and linting tools, and run them as part of your CI pipeline. Then, your Definition of Done includes “the code builds successfully”. These style checking tools can be used to efficiently enforce a style guide, though some aspects of a style guide cannot be reasonably automated. Things that are easy to automate are formatting, naming conventions, and documentation.

    If you don't already have a style guide or coding conventions, adding a tool might lead to lots of erroneous warnings. It might initially be best to start with a minimal configuration and add stricter rules on demand (and occasionally slip in some refactoring to make the existing code conform to more rules).

Your Answer

By clicking "Post Your Answer", you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.