https://github.com/greatislander/laser-eye-comments

Content for a lightning talk on code comments.
https://github.com/greatislander/laser-eye-comments

comments jsdoc phpdocumentor restructuredtext

Last synced: 7 days ago
JSON representation

Content for a lightning talk on code comments.

• Host: GitHub
• URL: https://github.com/greatislander/laser-eye-comments
• Owner: greatislander
• Created: 2020-09-03T14:56:57.000Z (over 4 years ago)
• Default Branch: dev
• Last Pushed: 2020-09-03T15:39:22.000Z (over 4 years ago)
• Last Synced: 2024-11-18T22:06:50.568Z (2 months ago)
• Topics: comments, jsdoc, phpdocumentor, restructuredtext
• Language: Python
• Homepage:
• Size: 22.5 KB
• Stars: 0
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# Code Comments

> 4. The public API is commented. ([source](https://wiki.fluidproject.org/display/fluid/Laser+Eye+Checklist))

## What

Generally code comments take one of three forms:

1. File-level comments, which provide information about the contents of a file.

2. Block-level comments (sometimes known as docblocks), which document the API or usage of a specific function, method or class.

3. Line-level comments, which provide inline documention of a function or method's internal operations.

## Why

> Code can only tell you _how_ the program works; comments can tell you _why_ it works. ([source](https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/))

File-level comments help provide a sense of the overall structure of the project (the more complex the project, the more helpful they are). Block-level comments provide documentation for the API (for example, they often tell what input is required and what output is expected). Line-level comments can clarify complex code within a function or method, provide contextual references to external resources, and document areas where future improvements may be needed.

Code comments written according to a specification (e.g. JSDoc, phpDocumentor, or one of various Python docstring formats) can be used to automatically generate HTML or other documentation for an application.

## How

- [JavaScript](https://github.com/greatislander/laser-eye-comments/tree/dev/js/)

- [PHP](https://github.com/greatislander/laser-eye-comments/tree/dev/php/)

- [Python](https://github.com/greatislander/laser-eye-comments/tree/dev/python/)