Features in Detail - Document code: better, faster, tidier, cheaper
With a single keypress or menu command, the extension can:
- Create or update highly configurable
Documentation XML,
Doxygen,
Qt QDoc,
JavaDoc or
Natural Docs-format
documentation comments for code elements
(file, namespace, class, interface, template, struct, enum, variable, property, event, delegate,
function/method, etc)
in your code. Atomineer will automatically generate a clear starting point for your documentation,
with context-sensitive descriptions for all parameters, generic type parameters, thrown exceptions and
return codes, using contextual information such as existing documentation from related base class and
override methods/properties and existing parameters within the same class, and generating accurate and specialised documentation for
thousands of common function, class and parameter types. Comments can be automatically converted between
all of the supported formats and from bespoke formats to update legacy documentation to a new standard.
It can also optionally reformat the updated text using automated indentation, word wrapping and
XML validation/correction to keep your code documentation legal, accurate, informative and tidy
with a minimum of effort on your part.
An absolutely essential tool for any team wishing to write maintainable code.
- Automatically document/convert every code element within a namespace/interface/class/struct/enum scope.
- Word-wrap the text in a block comment.
- Instantly align similar lines of code (e.g assignments, parameters, etc) into columns to improve clarity,
readability and editability.
- Hide all documentation comments and/or attribute declarations using Visual Studio's Outlining facility.
- Auto-generate a C++/C skeleton implementation (in your source file) from a declaration (in a header).
- Open the matching header for a given C++ source file, or the matching source file for a given header.
- Add a C++/C declaration to your header for any existing method implementation.
- Create C# Auto-Properties, Explicit Properties or C++ Accessor functions from member variable declarations.
- Copy code to the clipboard in a clean format ideal for use in applications such as
when writing Word .doc Documentation, or emailing examples to team members.
|
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) and
SandCastle (.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.
|
Why choose Atomineer?
Atomineer Pro Documentation doesn't simply regurgitate the name of a code element with basic word re-ordering.
It uses thousands of rules to try to generate the most meaningful possible documentation based on naming,
types, context and existing documentation (e.g. within a class or its base classes).
Here are some examples of the comments that Atomineer will generate purely from the name and type
of a parameter:
Parameter | Auto-generated documentation |
char *serialIOBuff | [in,out] If non-null, buffer for serial i/o data. |
string userInfo | Information describing the user. |
IdGroup programIds | List of identifiers for the programs. |
CString config_fname | Filename of the configuration file. |
int processIndex | Zero-based index of the process. |
params object[] fmtValues | A variable-length parameters list containing format values. |
For more examples of classes, methods, parameters and return types see:
Documentation XML format comments
and Doxygen format comments.
...and Atomineer doesn't stop at documentation generation - it includes many special features to help you
create and maintain documentation comments, such as duplicating existing documentation, providing live typing
aids to speed up commenting, spell-checking to improve comment quality, word-wrapping and reformatting
facilities to keep comments tidy, and a live preview window so you can read the documentation more easily.
Compare the features of Atomineer Pro Documentation with other extensions
and you will see what incredible value for money it is. Then download the free trial
to see for yourself how well it performs. And if it's missing something you need,
email us and we'll do
what we can to add support for you.
|
Copyright © 1996-2023 Atomineer. All Rights Reserved. Any trademarks reproduced in this text are the property of their respective owners
- Contact us
- Company Info
|
| | | |