I am going to practice (again) when writing code comments. I have multiple projects all over my repositories which are quite all over the place, but I must know that I have done some projects which are I deemed good and cool.
Now, I need to review my code and project files - take out which ones that are good and improve those which can be improved.
Writing code is like writing a poem. Every Software Engineer has their own ways of making implementations to fulfill
requirements, and so it is very important to put lines of comment in a src file for every Java class or methods.
Remember, don't comment or explain what the code is doing, but rather tell why you implemented or wrote it. Moreover, providing some little contexts on what the code is doing is also very important but don't put long paragraphs explaning everything.
A doc comment is written in HTML and must precede a class, field, constructor or method declaration. It is made up of two parts -- a description followed by block tags. In this example, the block tags are @param, @return, and @see.
Semantic Formatting is the way an engineer follows convention, standardss, and general practices when writing code. For example, when we are using Python in a project, we should remember to write clean code according to Python standards. And in this case, we are trying to write code and use comments which are in-line with Oracle standards said from their documentation.
Semantic formatting refers to the practice of structuring and formatting your code in a way that aligns with the semantics, or meaning, of the code. This goes beyond just adhering to the syntactic rules of the language and focuses on making the code more readable and expressive. Here are some key aspects:
- Consistent Naming Conventions:
Meaningful names for variables, functions, and classes that reflect their purpose. Consistent use of camelCase, PascalCase, or snake_case for different elements. Indentation and Whitespace:
- Consistent indentation to represent the structure of the code.
Proper spacing to enhance readability. Use of whitespace around operators and keywords for clarity.
- Commenting:
Clear and concise comments to explain complex logic or the purpose of certain code blocks. Avoid unnecessary comments that state the obvious; focus on explaining why something is done rather than what is done.
- Consistent Code Structure:
Group related code together. Follow a consistent structure for classes, methods, and other code blocks. Logical ordering of methods and members within a class.
- Semantic HTML and CSS:
In web development, semantic HTML involves using tags that convey the meaning of their content (e.g header, nav, article) In CSS, semantic classes and IDs can make styling more intuitive (e.g., using .error-message instead of .red-text).
- Use of Design Patterns:
Implementing design patterns that convey the intention of the code and provide proven solutions to common problems.
- Consistent Code Formatting:
Following a consistent code style across the entire project.
Utilizing automatic code formatters to enforce consistency.
- Avoiding Magic Numbers and Strings:
Instead of using "magic" numbers or strings directly in the code, use constants or enums with meaningful names. Semantic formatting aims to make code more readable and maintainable, reducing the cognitive load for developers. It facilitates collaboration among team members and makes it easier for others (or your future self) to understand and modify the code. It's not just about making the code look nice but ensuring that the structure and style enhance the communication of the code's purpose and functionality.
These are the comment block tags which I use to my projects. I found these tags helpful when reading and looking at my code.
- @author
- @note
- @description
- @date
- @return
- @param
- @method
However, there are official block tags according to Oracle:
- @param
- @returns
- @throws
- @see
- @depcrecated
- @since
- @version
Java SE 20
This will be updated from time to time
You may create a pull request to improve my code and correct if there is any. I would be glad for that as I want to get much, much better in Java and following language conventions and practices.
