“Technical Writing Guide” to Get Programmers Off Work Early

For programmers, they are either writing bugs or fixing bugs every day~

In addition to non-stop coding, doing some details can undoubtedly help us get off work earlier.

No, a foreign front-end developer summed up a “Technical Writing Guide for Programmers” on how to correctly write code comments, write PR descriptions, and so on.

Although these things are trivial, if everyone is not standardized, how painful is it to maintain the code?

I know everything.

So, what should we pay attention to?

Programmer Technical Writing Tips

1. Code comments

Code comments are written both for yourself and others. In particular, the latter should be written clearly and clearly.

In this regard, the guide gives three points of attention:

(1) Write key information, not nonsense

A simple example.

Wrong spelling:

 red = 1.2 // Multiply red by 1.2 and re-assign it（将red变量2，再赋值给它）

Correct spelling:

 red *= 1.2 // Apply a 'reddish' effect to the image（给图像应用“reddish”效果）

Well understood. Don’t repeat the code, write the deeper meaning of the code, provide incremental information.

(2) Comments should be updated after code changes

There is this line of code and comments:

 cities = sortWords(cities) // sort cities from A to Z（由AZ排序城市变量）

But the author wrote it wrong, in fact, the sortWords function is to sort from ZA.

But it doesn’t matter, just add a reversal, so the code becomes like this:

 cities = sortWords(cities) // sort cities from A to Z（由AZ排序城市变量）
 cities = reverse(cities)

Then the problem arises. Others don’t know this process, and they only see the comments on the first line. They will naturally think that the cities are first ranked according to AZ, and then reversed from Z to A.

This is the consequence of changing the code without changing the comments.

Of course, this example is exaggerated. But things like that do have the potential to cause unnecessary trouble.

(3) The anti-common method must be annotated

Sometimes, in order to be compatible with various browsers, you may add some unconventional writing methods to the code. At this time, you must pay attention to writing comments.

Otherwise, others may think “what’s this written” at first glance, and they will change it for you…

example:

 function addSetEntry(set, value) {/ Don't return set.add because it's not chainable in IE 11. （不要返回“set.add”，它跟IE 11不兼容）/set.add(value);return set;

}

Here’s a little bit of a break, the guide mentions:

No matter what you write, try to use the active voice as much as possible, because normal people need to switch to the active voice in their minds when they see sentences in the passive voice, and there is no need to increase the processing time.

(4) Post a link to the solution

Sometimes you encounter a problem and go to the Internet to find a solution, then you can attach the link for easy review, just in case.

Some netizens said that this suggestion is very useful, because sometimes he forgets why he wrote the code like this.

2. PR description

How to write PR description when submitting code is also an important detail, which is related to the efficiency of code review.

Although many teams have norms within themselves, some people just don’t follow them.

The following points in particular need to be noted:

(1) Write in detail, do not write vague expressions such as “adding patches” and “fixing bugs”;

Positive example:

eg1. Support custom srcset attribute in NgOptimizedImage

eg2. Add explicit selectors for all built-in ControlValueAccessors

(2) Don’t submit thousands of lines of code at once, try to submit a small part of it as much as possible to reduce the review pressure.

3. Report bugs

When submitting a bug report, try to:

(1) Use screenshots/movies to assist text description problems;

(2) Provide precise steps to reproduce the problem;

(3) Provide the possible reasons for your analysis.

4. Microcopy

ps. For the domestic situation, this part of the content is more suitable for product managers to eat.

Microcopy refers to the prompts that pop up on your web page/APP when user operation/system errors occur.

How to write this prompt is also important:

(1) Avoid using technical terms.

I believe that many people have encountered a line of technical prompts that you cannot understand, such as “execution timeout”, which makes you do not know what happened or what to do.

To avoid this, it’s best to tell the user what to do without explaining what went wrong.

(2) Don’t “blame” the user.

Imagine you open a website, log in, and you’re told: “Your email/password is incorrect.”

This expression can be subconsciously uncomfortable and make users feel “silly”.

Correct way:

“Sorry, the email password combination is incorrect. We can help you recover your account.”

Another point: try to avoid all capital letters or use exclamation marks, which can lead to hostility.

(3) Appropriate use of humorous tone, sometimes forced humor is worse than no humor.

The original guide also includes some suggestions on how to communicate with customers. Interested friends are welcome to click the link to read~

Finally, do you have anything to add about technical writing for programmers?

The text and pictures in this article are from qubits