Coffee break #79. 10 mistakes Java developers make that prevent them from achieving success. A Developer's Guide to Writing Meaningful Code Comments

10 Mistakes Java Developers Make That Prevent Their Success

Source: Dev.to Based on my experience, I have compiled a list of 10 mistakes that developers make that prevent them from achieving success:

1. Don't write unit tests

Developers who don't write unit tests make more mistakes in their code. This leads to product instability and customer dissatisfaction.

2. They don’t check the code manually

Even if you completely cover your code with unit tests, there is still a chance that you missed something. It is always recommended to manually test your code before submitting it for review. This way you can detect errors at the development stage.

3. They think: “This will never happen.”

Developers often make mistakes when writing new code, thinking that certain scenarios will never happen. In the end it turns out that they are wrong. Handle all scenarios where code may be executed. Defensive programming methods will help you with this.

4. Don't get feedback

Regularly solicit feedback from other developers and users. Share your opinion with your colleagues.

5. They don’t check the functionality of the code.

Often developers write their code, but do not check its functionality. As a result, when the code reaches production, it creates various problems.

6. Write long procedural code

It's very easy to write long methods with a lot of logic. By doing this, programmers implement the same logic in many places. Projects with a significant number of small methods have much better code reuse and are much easier to maintain.

7. They don’t know the tools

Tools are an extension of your hands. The better you know them, the more productive you will be. You should be very familiar with the IDE you are using. Learn quick commands, there are always commands that will help you be even more productive. In IntelliJ IDEA these are Sonar Lint, Spot bugs and Code Metrics.

8. Ignore problems in the code

The developers who work on the most successful products constantly change the code. Don't be afraid to refactor your code. If your code is unit tested, there is little chance of regression. Developers often ignore problematic code. As a developer, you are responsible for maintaining the application in good condition. For this reason, fix any problems you find.

9. They code without realizing the consequences.

Developers should NEVER make changes to code and release it into production without understanding the consequences. The code may produce correct results for the given test values. However, there may be scenarios in which this could lead to unpredictable results and create serious problems. “Unpredictable” coding often happens when developers use functions from libraries that they don't fully understand. This can also happen when a developer fixes a problem without understanding the solution.

10. Don't ask for help

Developers are not very sociable people. They like to solve problems on their own. But the era when one developer himself creates a product from start to finish is over. Software development is a team activity. When you encounter a problem while programming, try to solve it yourself. But don't waste too much time if you can't find a solution. There is a high chance that some of your colleagues have already encountered the same problem and know the solution. This will save time and increase productivity.

A Developer's Guide to Writing Meaningful Code Comments

Source: Stepsize In most cases, you are not the only one working on the same project or codebase. This means that other people must understand your code. This is also true for code comments. Developers often write “quick and dirty” comments without much context, leaving their colleagues confused about what the author was trying to say. This is bad practice and creates more confusion than clarity. Having clear code comments helps other developers. A code comment that describes a function, its rationale, input, and output speeds up the learning process for other developers. On the other hand, code comments lead us to the question: is it worth writing them? A significant group of developers oppose writing code comments. The reason is that the code, in their opinion, is self-explanatory. If another developer can't understand the purpose of your code by looking at it, then it's bad code. Perhaps this is true. But think about the small effort required to comment out code and the potential benefits it brings. Code comments are important to speed up the onboarding process for any developer, especially juniors. Let's look at the different types of code comments.

1. Comments on the documentation.

The main purpose of such comments is to quickly clarify the purpose of a file or component. Instead of reading the entire code of a component to understand what it does, you can add a code comment at the top of the `index` file. This will help explain what this component does. I'm not a big fan of this type of comment because it clutters up the code a bit. I think these types of architecture comments should be in your internal documentation where you can centrally maintain and discuss the architecture of your project. However, open source projects really need them.

2. Comments on functions.

This is the most useful type of comment. They describe the function's purpose, its parameters, and its output.

/**
 * @desc Creates a welcome message
 */
function sayHello(name) {
    return `Hello ${name}`;
}

3. Logical comments.

These are comments within functions to clarify complex code paths. As you might have guessed, the presence of such comments indicates that your code is too complex. In addition, logical comments often contain too much detailed information. The level of detail will create more chaos and reduce the readability of your code. Here is an example of an overly detailed code comment.

let date = new Date(); // store today's date to calculate the elapsed time

Code Commenting: 4 Best Practices for Commenting

1. Use code annotations or tags

Many programming languages ​​define standards for commenting code. Java uses Javadoc , while JavaScript uses the JSDoc code commenting system , which is supported by many documentation tools. For functions you must include the following code tags:

• @desc - description of your function
• @param - all input parameters that the function accepts. Be sure to specify input types.
• @returns - returned output. Be sure to specify the output type.
• @throws is the type of error that the function can throw.
• @example - one or more examples that show the input and the expected output.

Here is an example Lodash code for the chunk function .

/**
 * Creates an array of elements split into groups the length of `size`.
 * If `array` can't be split evenly, the final chunk will be the remaining
 * elements.
 *
 * @since 3.0.0
 * @category Array
 * @param {Array} array The array to process.
 * @param {number} [size=1] The length of each chunk
 * @returns {Array} Returns the new array of chunks.
 * @example
 *
 * chunk(['a', 'b', 'c', 'd'], 2)
 * // => [['a', 'b'], ['c', 'd']]
 *
 * chunk(['a', 'b', 'c', 'd'], 3)
 * // => [['a', 'b', 'c'], ['d']]
 */
function chunk(array, size = 1) {
  // logic
}

2. Explain the reason for your actions

Many developers use comments to describe what their code does. When doing so, be sure to include why you created a particular feature or component. This information is called context. Context is important to give developers more information about the design decisions behind a feature or component. Context is critical when other developers want to make changes to your feature or component. Below you can see a bad example of commenting code without context.

/**
 * Sets the label property of a new form.
 *
 * @param label text for label of form
 */
function setFormLabel(label) {
    // logic
}

3. Don't link to other documents or comments

It is not recommended to link to other code comments or internal documents that explain a feature or component.

/**
 * Sets the label property of a new form.
 *
 * @see {@link https://myinternaldocument.com}
 */
function setFormLabel(label) {
    // logic
}

4. Write comments while coding

This may seem obvious, but many developers (myself included) neglect this rule. Leaving comments for later is bad because you may forget some of the logic you wrote, which will lead to lower quality code comments. This is especially true if you've been working on the same pull request for several days. It's better to write comments when you've just finished a feature or module. Remember to keep code comments as brief as possible. You don't need to spend more time writing comments than you do writing the code itself.