Importance of Editing and Proofreading

I've experienced this time after time again, many developers don't proofread their work. I don't know why some developers have this urgency to submit their code for review right after they get it working without doing the important step of editing and proofreading.

Do you remember in school when you finished that essay or research paper, you edited and proofread it before submitting right? I believe this should apply to our source code too. In a way, source code is a developer's form of written communication.

After you finished completing a portion of work that is ready for submission or code review, consider doing the following.

Editing:

• Does your code integrate properly into the overall system. As an analogy, writing the next chapter in the book or the next paragraph in the essay.
• Using the right data structures for impact and efficiency.
• Are you expressing what you are doing clearly and to the point.
• Using the language as best as you can, e.g. don't write your Swift code like Java, or your JavaScript code like C#.
• Are you being overly verbose or too compact with your code.
• Have you communicated your intentions clearly that would be understood to another developer and not just the computer.

Proofreading:

• Have you checked for spelling, grammar, and typing mistakes. Linting helps but you'll be surprised how often people ignore lint warnings.
• Are you conforming to the style of the existing code and being careful of things that a linting tool might not catch.
• Did you go through a checklist of common runtime errors.

I've heard reasons for not doing this, most of the time it comes down to "I want to submit my code as soon as possible. I don't want to be waiting around and have my code get out of date with the rest of the codebase." Our source code is not only how we make the computer work but also a form of communication between developers. I encourage all developers, especially newer developers, to foster the same habit you have with other written communications. Edit and proofread your work before submitting.

Comments

[Lester Romano]

This is why code review is a must on a large codebase.

[Justin Lam]

I think what I'm trying to convey is to do some due diligence at the point before a code review is submitted.

[Lester Romano]

Yes I understand. Another thing that I hate (other than not having a due diligence to review his code) is not having the diligence to request for a review which really sucks.

[Michiel Hendriks]

Somebody else has to do that for me. I can read something I wrote 20 times and not see an obvious error. My brain (thinks it) knows what's there and will ignore a lot what my eyes are telling.
This is why you do (code) reviews of other people's work.

[Justin Lam]

I understand. It's not able being completely perfect, but one should take time to at least do 1 or 2 passes before submission.

I know for book writing, they are dedicated editors because the author is guaranteed to make mistakes. Perhaps this might be something we may need in teams, a dedicated "editor" for our source code.