Contributing and Debugging/PR-Guidelines.md : Added guidelines for documentation and comments.#1279
Contributing and Debugging/PR-Guidelines.md : Added guidelines for documentation and comments.#1279TheKnightSky wants to merge 2 commits intohyprwm:mainfrom
Conversation
|
|
||
| Most users expect the documentation to be under README.md or CONTRIBUTING.md. | ||
| A large number of issues created on Hypr projects are because of not reading the documentation. | ||
| It is better to include a line in every README.md, declaring that [wiki.hypr.land](https://wiki.hypr.land/) is the official documentation for all Hypr projects, and to read the documentation before making an issue. |
There was a problem hiding this comment.
what does this refer to?
Take the example of hyprlauncher, the about section of the repo has linked to the wiki page specific to hyprlauncher, whereas repos like hyprutils, xdph, hyprpicker etc, which do have wiki specific pages, don't have it linked in the about page, neither in the readme.md.
People viewing a specific project without knowing about the hypr ecosystem, would have no idea that the wiki exists. This lead to some, including me, either getting confused or creating issues.
I would say that in the about page we could provide the link to the specific part of the repo to the wiki and in the readme.md, we generally could say wiki.hypr.land is the official documentation site.
There was a problem hiding this comment.
Take the example of hyprlauncher, the about section of the repo has linked to the wiki page specific to hyprlauncher, whereas repos like hyprutils, xdph, hyprpicker etc, which do have wiki specific pages, don't have it linked in the about page, neither in the readme.md.
No. I said hyprlauncher does have it. But repos like hyprutils, xdph, hyprpicker don't have it. Please check them out. Sorry was away for a few days.
|
|
||
| It is best practice to include comments for code. | ||
| Good documentation and comments is as important as good code. | ||
| You can still contribute to the development of open source projects even without development skills, by helping out with documentations and non-technical work. |
There was a problem hiding this comment.
Too positive of comments. I, for once, disagree. I believe your code should be as clean as possible, and comments should only be used when it's necessary for code to not be self-descriptive
There was a problem hiding this comment.
I understand your view, looking at clean optimized code without codes is indeed pleasing. But comments are necessary for any relevant information as well, not just specific to the code.
comments should only be used when it's necessary for code to not be self-descriptive
Fair enough,Explain what the code does, rather than how it does it; avoid explaining how, unless the logic is non-obviousseems a bit much then. I would change it to something along the lines of "Use comments to describe or explain the code when its not self-descriptive" and remove stuff like "Prefer adding comments to functions and classes" and tone down/remove the relevant examples.
I do still stand on the following:
- Comments are for _others_ to understand code, not as logs for what has been done to the code
- Clarify why certain decisions were made for the code, if it is relevant on a technical standpoint
- Use terms like NOTE or TODO, to communicate current limitations and/or future plans.
- Follow the style of existing comments
I'll make the edits once you let me know.
There was a problem hiding this comment.
I would change it to something along the lines of "Use comments to describe or explain the code when its not self-descriptive" and remove stuff like "Prefer adding comments to functions and classes" and tone down/remove the relevant examples.
yup thats ok
2 participants
There was no documentation about documentation and comments, I added them.