Shulou(Shulou.com)06/03 Report--

This article introduces the knowledge about "what are the side effects of code comments". In the actual case operation process, many people will encounter such difficulties. Next, let Xiaobian lead you to learn how to deal with these situations! I hope you can read carefully and learn something!

Code comments vs code documentation

Code comments contain code documentation (class, method, attribute, constant description)

Code documentation necessary, non-code documentation unnecessary

Use scenarios for code comments

New students start, quickly grasp the context.

Doubt when reusing methods, quickly query comments to avoid method side effects.

Review the code implementation to restore the original implementation intent.

Despotism disobeys children and destroys technological beliefs. (Definition vague, can be used to refer to deer as horse)

Side effects of code comments

Good Code> Bad Code + Comments (affects code cleanliness)

Carry historical baggage (historical TODO, historical background details)=> dare not delete

No standard, unable to quantify, unable to evaluate (large individual differences, forced promotion, easy to affect development efficiency, implementation of code comments to do not read code comments)

May cause teams to fall into chaos without thinking about code structure design

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None): """Fetches rows from a Bigtable. Retrieves rows pertaining to the given keys from the Table instance represented by big_table. Silly things may happen if other_silly_variable is not None. Args: big_table: An open Bigtable Table instance. keys: A sequence of strings representing the key of each table row to fetch. other_silly_variable: Another optional variable, that has a much longer name than the other args, and which does nothing. Returns: A dict mapping keys to the corresponding table row data fetched. Each row is represented as a tuple of strings. For example: {'Serak': ('Rigel VII', 'Preparer'), 'Zim': ('Irk', 'Invader'), 'Lrrr': ('Omicron Persei 8', 'Emperor')} If a key from the keys argument is missing from the dictionary, then that row was not found in the table. Raises: IOError: An error occurred accessing the bigtable.Table object. """ pass /** * Tests if the specified object is a key in this table. * * @param key possible key * @return {@code true} if and only if the specified object * is a key in this table, as determined by the * {@code equals} method; {@code false} otherwise * @throws NullPointerException if the specified key is null */ public boolean containsKey(Object key) { return get(key) != null; } Personal advice for code comments

Control the granularity of comments (generally to the code document level, when you need fine-grained comments, consider whether to extract this logic to write)

Clear comment scope (describes a line of code, describes a Loop)

Comments leave no baggage (historical background information, unprocessed TODO, code comments at baseline document level maintained)

As a supplementary explanation of complex logic (examples of intermediate result formats, why catch exceptions, why not)

Understand the goal of code comments, readable, effective (empathy)

How to reach consensus on code comments?

brain storm

trial

Phase-back comments, case sharing (dedifferentiation)

"What are the side effects of code comments" is introduced here, thank you for reading. If you want to know more about industry-related knowledge, you can pay attention to the website. Xiaobian will output more high-quality practical articles for everyone!

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.