Atomineer Pro Documentation for Visual Studio (2005..2026) (original) (raw)

Code Documentation - Why do it?

When programming, understanding what classes and methods are for, how to use them, and how they work is critical for rapid development/maintenance and avoiding bugs due to misunderstandings. It's important to write this information down - to share this knowledge across team, as well as for programmers to recall the fine details of code they haven't touched for a long period.

Many programmers write 'self documenting' code, where clear and descriptive naming conventions make it easier to understand code quickly. Documentation comments take this a step further by summarising that information in a single place rather than having to read through often quite complex source code. In addition, and most importantly, code documentation can tell you the things that 'self documenting' code never mentions:

* What exceptions will a method throw? * Can I pass a null in to this parameter? * What is the legal range for an integer parameter? * What is the return value that describes 'not found'?

Writing 'self documenting' code is just the first and most basic step of writing well documented, maintainable code.

In addition, the information from documentation comments can be used by Visual Studio's Intellisense system, with the information you need displayed live in tooltips as you type your client code.

There are also tools such as Doxygen (all languages) andSandCastle (.NET languages) that can be used to generate professional external documentation like that used in MSDN - essential for libraries and other code that will be shipped to third parties, as well as being extremely useful for internal use by your team.

There are just three problems:

• Writing documentation can be very time consuming
• Programmers usually prefer to write code, so the documentation (if written at all) suffers
• Comments easily get 'out of sync' with the code, making them useless or even misleading

Atomineer eliminates these problems:

• It minimises the effort involved in documenting. A high proportion of documentation content is repetitive and easily filled in by the computer. Although you often have to add to the comments Atomineer provides, it instantly builds a solid basis for your comment.
• It summarises as much information as possible about a code element in a standardised form, making it a quick to read format regardless of which programmer(s) wrote the code.
• It keeps the documentation in sync with changes to the code (e.g. when parameters, return values or thrown exceptions are changed in a method, or get/set accessors are added to a property).
• In many languages, XML Documentation comments are picked up by Visual Studio and presented within intellisense tool-tips as you type method-calls, which makes writing code much easier, quicker and less error prone.
• Atomineer goes much further than any comparable extension - it keeps documentation and surrounding code tidy by enforcing line breaks, adjusting formatting and element ordering, indentation, punctuation and word wrapping - It works hard to keep comments tidy and readable on your behalf. All these options are configurable so it's easy to ensure all comments are in the precise style you require.
• Teams using Atomineer often find that the extension actively promotes more consistent naming practices throughout the team, as good naming produces a better starting point for documentation.
• It encourages developers to write documentation and keep it up to date. Programmers want to write code, and AtomineerUtils allows to focus on what they enjoy while still producing great docs.
• In a similar way to unit tests, writing documentation encourages programmers to think more about their code and how it will be used by others. This generally leads to improved designs and lower defect rates in the associated code.
• Typically an Atomineer developer saves around 1-2 working weeks per year just in the production of their documentation - a massive cost saving even before we factor in the less tangible down-stream time-saving and quality benefits.