Skip to content

Updated AV2310 for local functions #155

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
bkoelman wants to merge 1 commit into from
Closed

Updated AV2310 for local functions #155

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion _pages/2300_DocumentationGuidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Following the MSDN online help style and word choice helps developers find their
**Tip:** The tool [GhostDoc](http://submain.com/products/ghostdoc.aspx) can generate a starting point for documenting code with a shortcut key.

### <a name="av2310"></a> Avoid inline comments (AV2310) ![](/assets/images/2.png)
If you feel the need to explain a block of code using a comment, consider replacing that block with a method with a clear name.
If you feel the need to explain a block of code using a comment, consider replacing that block with a method or local function with a clear name.
Copy link
Copy Markdown
Owner

@dennisdoomen dennisdoomen May 10, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure about this one. If the code becomes that much unreadable, a local function will not really help focusing on the current body. In that case, I would prefer to have a separate method or to properly encapsulate a concept that is now represented by primitive types. See also https://www.continuousimprover.com/2015/10/9-simple-practices-for-writing-better.html

Copy link
Copy Markdown
Contributor Author

@bkoelman bkoelman May 10, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense. Let's discard this PR then.


### <a name="av2316"></a> Only write comments to explain complex algorithms or decisions (AV2316) ![](/assets/images/1.png)
Try to focus comments on the *why* and *what* of a code block and not the *how*. Avoid explaining the statements in words, but instead help the reader understand why you chose a certain solution or algorithm and what you are trying to achieve. If applicable, also mention that you chose an alternative solution because you ran into a problem with the obvious solution.
Expand Down