Recommended Comments
C# documentation comments use XML elements to define the structure of the output documentation. One consequence of this feature is that you can add any valid XML in your documentation comments. The C# compiler copies these elements into the output XML file. While you can use any valid XML in your comments (including any valid HTML element), documenting code is recommended for many reasons.
Recommended Comments
What follows are some recommendations, general use case scenarios, and things that you should know when using XML documentation tags in your C# code. While you can put any tags into your documentation comments, this article describes the recommended tags for the most common language constructs. In all cases, you should adhere to these recommendations:
Some of the recommended tags can be used on any language element. Others have more specialized usage. Finally, some of the tags are used to format text in your documentation. This article describes the recommended tags organized by their use.
The tag gives you a way to indicate that a word in the code comments, for example in a or block refers to a parameter. The XML file can be processed to format this word in some distinct way, such as with a bold or italic font.
Inherit XML comments from base classes, interfaces, and similar methods. Using inheritdoc eliminates unwanted copying and pasting of duplicate XML comments and automatically keeps XML comments synchronized. Note that when you add the tag to a type, all members will inherit the comments as well.
Add your XML comments in base classes or interfaces and let inheritdoc copy the comments to implementing classes. Add your XML comments to your synchronous methods and let inheritdoc copy the comments to your asynchronous versions of the same methods. If you want to copy the comments from a specific member, you use the cref attribute to specify the member.
The tag lets you refer to comments in another file that describe the types and members in your source code. Including an external file is an alternative to placing documentation comments directly in your source code file. By putting the documentation in a separate file, you can apply source control to the documentation separately from the source code. One person can have the source code file checked out and someone else can have the documentation file checked out. The tag uses the XML XPath syntax. Refer to XPath documentation for ways to customize your use.
Some teams strongly prefer a longer line length. For code maintainedexclusively or primarily by a team that can reach agreement on thisissue, it is okay to increase the line length limit up to 99 characters,provided that comments and docstrings are still wrapped at 72characters.
For decades the recommended style was to break after binary operators.But this can hurt readability in two ways: the operators tend to getscattered across different columns on the screen, and each operator ismoved away from its operand and onto the previous line. Here, the eyehas to do extra work to tell which items are added and which aresubtracted:
Block comments generally apply to some (or all) code that followsthem, and are indented to the same level as that code. Each line of ablock comment starts with a # and a single space (unless it isindented text inside the comment).
Names of type variables introduced in PEP 484 should normally use CapWordspreferring short names: T, AnyStr, Num. It is recommended to addsuffixes _co or _contra to the variables used to declare covariantor contravariant behavior correspondingly:
Using comments throughout your code can help other developers in situations like this one. Comments help other devs skim through your code and gain an understanding of how it all works very quickly. You can help ensure a smooth transition by choosing to comment your code from the outset of a project.
Start writing comments for yourself in your own code. Make it a point to include simple comments from now on where necessary. Add some clarity to complex functions, and put a docstring at the top of all your scripts.
Knowing how to write comments in Python can make life easier for all developers, including yourself! They can help other devs get up to speed on what your code does, and help you get re-acquainted with old code of your own.
Another misuse of comments is to provide information that should have been in the code. A simple example is when someone names a variable with a single letter and then adds a comment describing its purpose:
[Peter Samson] was particularly obscure in refusing to add comments to his source code explaining what he was doing at a given time. One well-distributed program Samson wrote went on for hundreds of assembly-language instructions, with only one comment beside an instruction that contained the number 1750. The comment was RIPJSB, and people racked their brains about its meaning until someone figured out that 1750 was the year Bach died, and that Samson had written an abbreviation for Rest In Peace Johann Sebastian Bach.
I find it very helpful to note the date of changes as part of the comments.The same comment line (with date) I repeat in the head of the module ordered by date descending.In this way I have a kind of TOC in every module, showing the last changes.
One great use for comments, which has nothing to do with descriptive variable names, is to explain why code changes over time. For example, if the algorithm for choosing the best node changes, the comments should describe that. Even if the code for the old algorithm gets deleted, the comments should remain and describe what it used to do, so that developers can decide whether to resurrect that old code, or to avoid it like the plague.
Years earlier, during my long employment in a large company, I was made to understand that the written code is owned by the company you work for and therefore MUST necessarily be written by someone (or more than one) and then MUST to be read-understood-revised by someone else. So we all understood (some more, some less) the importance of comments, flow charts or representation as a state machine.
I have only one rule for comments. Only use them to express information which must be retained and absolutely cannot be conveyed using the programming language itself. You can get a hell of a long way with a meaningful naming regime in your code.
Quibble with Rule 2: I would not trust a variable name to describe the contents of the variable. (Or a constant.) I would not try to name a variable comprehensively either. If need be, use comments to say what is really going on. An expressive name is good, but a long name is not so good for several reasons; you can mistype it, or you can confuse it with other similar variable names. And if a variable only needs to exist for five lines, by all means call it n. Or tmp. Or tmp_1750.
So, those types of comments are basically describing WHAT a chunk of code does. I find them useful when trying to find certain functionality in the code later. Without those comments, trying to find something in the code involves reading a bunch of lines of code, deciphering what the code is doing, and then realizing that is not the code you are looking for. Repeat until you finally find the code you are looking for. A simple comment describing WHAT a block of code does would prevent a lot of wasted time and effort.
Interesting blog, comments indeed need to be added professionally to the code and should be kept well separated from the code as it could create several bugs and leave the programmer scratching their head while debugging. The most important tips for me while adding comments is that the comments should be precise as I have seen a lot web app developers writing long lines and sometimes even paragraphs as comment when it could be much more precise.
Also, in addition to the good rules here, one super important rule that is missed, is that extracting methods can remove needs for comments AND add all other extra benefits of abstraction, modularization and simpler context.
But now, Yelp just shows nine reviews. The rest of them are hidden. Down at the bottom of the page, there's a link to "not currently recommended reviews." If you click there you'll see the other 40, but that faded link isn't easy to see.
I am particularly guilty of this, embedding non-constructive comments, code poetry and little jokes into most of my projects (although I usually have enough sense to remove anything directly offensive before releasing the code). Here's one I'm particulary fond of, placed far, far down a poorly-designed 'God Object':
This document describes the style guide, tag and image conventions we use in documentation comments for Java programs written at Java Software, Oracle. It does not rehash related material covered elsewhere:
At Java Software, we have several guidelines that might make our documentation comments different than those of third party developers. Our documentation comments define the official Java Platform API Specification. To this end, our target audience is those who write Java compatibility tests, or conform or re-implement the Java platform, in addition to developers. We spend time and effort focused on specifying boundary conditions, argument ranges and corner cases rather than defining common programming terms, writing conceptual overviews, and including examples for developers.
Thus, there are commonly two different ways to write doc comments -- as API specifications, or as programming guide documentation. These two targets are described in the following sections. A staff with generous resources can afford to blend both into the same documentation (properly "chunked"); however, our priorities dictate that we give prime focus to writing API specifications in doc comments. This is why developers often need to turn to other documents, such as Java SE Technical Documentation and The Java Tutorials for programming guides.
Ideally, the Java API Specification comprises all assertions required to do a clean-room implementation of the Java Platform for "write once, run anywhere" -- such that any Java applet or application will run the same on any implementation. This may include assertions in the doc comments plus those in any architectural and functional specifications (usually written in FrameMaker) or in any other document. This definition is a lofty goal and there is some practical limitation to how fully we can specify the API. The following are guiding principles we try to follow: 041b061a72