{"id":15969552,"url":"https://github.com/benapetr/programming-guidelines","last_synced_at":"2026-02-07T05:02:10.368Z","repository":{"id":145672426,"uuid":"176301958","full_name":"benapetr/programming-guidelines","owner":"benapetr","description":"Because there is too much shit software and bad programmers out there, I created this to help people write good software","archived":false,"fork":false,"pushed_at":"2019-05-21T12:00:58.000Z","size":15,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-25T21:52:03.164Z","etag":null,"topics":["guidebook","guidelines"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benapetr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-18T14:19:58.000Z","updated_at":"2019-05-21T12:01:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"1826db9d-7420-48ce-bf92-25e553f710e4","html_url":"https://github.com/benapetr/programming-guidelines","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/benapetr/programming-guidelines","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benapetr%2Fprogramming-guidelines","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benapetr%2Fprogramming-guidelines/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benapetr%2Fprogramming-guidelines/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benapetr%2Fprogramming-guidelines/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benapetr","download_url":"https://codeload.github.com/benapetr/programming-guidelines/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benapetr%2Fprogramming-guidelines/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29186742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-07T03:35:06.566Z","status":"ssl_error","status_checked_at":"2026-02-07T03:34:57.604Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["guidebook","guidelines"],"created_at":"2024-10-07T19:40:28.654Z","updated_at":"2026-02-07T05:02:10.343Z","avatar_url":"https://github.com/benapetr.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Programming Guidelines\nBecause there is too much shit software and bad programmers out there, I created this to help people write good software. Feel free to improve this with pull requests.\n\n# Error messages\nError messages **must** be verbose and clear. They need to say exactly what went wrong and if possible, why. If you don't want to show too much details so that you don't confuse average users, you should at least add a pointer for advanced users (error details can be found in /var/log/my_program). If you don't generate verbose error messages **your software sucks**.\n## Good\n* Error: unable to write to file /tmp/something.dat: permission denied\n* Error: unable to write to file /tmp/something.dat: not enough space left to write to device\n* Error: connection to server.org on port 545 TCP failed: socket closed\n## Bad\n* Error\n* This is error, that's all we know\n* Something wrong happened\n\n# Coding style\nThere is no best coding style, everyone prefers something else. I will add some examples for various languages later, but for now I would like to point out the important stuff:\n* Every project should follow some coding style for each programming language it contains\n* This project style should be adhered to within whole project and shouldn't be mixed with any other styles, the code should be consistent with the rest of code base\n* If anything you write is not obvious put comments there and explain your logic. If other people don't understand your logic, they will change your code and that may lead to disaster. Putting comments that explain your thinking, will avoid these disasters.\n\n## Names\nEach variable, class or function name should be \"self-documenting\". That means name should explicitly make it obvious what is it for. This is especially true for variables or functions that are somehow global. Higher scope demand better name. Index / loop variables that have very small scope can probably be generic \"i\" or \"x\" as their intention is obvious in such context.\n\n### Good\n```\nfloat vector_distance(Vector source, Vector target)\n{\n    return std::sqrt(std::pow(source.X - target.X, 2) + std::pow(source.Y - target.Y, 2));\n}\n```\n\n### Bad\n```\nfloat foo(Vector bleh, Vector meh)\n{\n    return std::sqrt(std::pow(bleh.X - meh.X, 2) + std::pow(bleh.Y - meh.Y, 2));\n}\n```\n\nIn case of programming languages that don't have static typing, it might be also a good idea to prefix variable name with its intended type as that will greatly improve code readability (everyone will know that str_foo is going to be a string in case they wonder, and they will not have to go through whole code-base just to figure that simple thing out).\n\n# Documentation\n* Undocumented code is just a bug waiting for removal. If anything is not documented, it shouldn't exist. Every single API and feature needs to be documented somehow.\n* Nobody cares about your code if it's not documented.\n* **Every documentation needs to contain examples. If it doesn't contain examples, it's not a documentation, it's garbage.**\n\n# Testing and optimization\n* Test and compile your code before you commit it\n* Try to run (or even better - develop) your software using very slow old computer, with slow CPU and little RAM. That's what most of the planet has. Users have worse computers than programmers. If your software run slow on that kind of computer, people will hate it. Optimize for average hardware.\n* Use unit tests if you can - they will make your life easier, continuous integration and unit tests are important.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenapetr%2Fprogramming-guidelines","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenapetr%2Fprogramming-guidelines","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenapetr%2Fprogramming-guidelines/lists"}