"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." – Martin Fowler
"There are only two hard things in Computer Science: cache invalidation and naming things." – Phil Karlton
Table of Contents
There are many great README templates available on GitHub; however, I didn't find one that really suited my needs so I created this enhanced one. I want to create a README template so amazing that it'll be the last one you ever need -- I think this is it. :D
Here's why:
- Your time should be focused on creating something amazing. A project that solves a problem and helps others
- You shouldn't be doing the same tasks over and over like creating a README from scratch
- You should implement DRY principles to the rest of your life 😄
Of course, no one template will serve all projects since your needs may be different. So I'll be adding more in the near future. You may also suggest changes by forking this repo and creating a pull request or opening an issue. Thanks to all the people have contributed to expanding this template!
Use the BLANK_README.md to get started.
Modern software is so complex that no one can understand all parts of a non-trivial project alone. The only way humans tame details is through abstractions. With abstraction, we focus on the essential and forget about the non-essential at that particular time. You remember the way you learned body biology?? You focused on one system at a time, digestive, nervous, cardiovascular e.t.c and ignored the rest. That is abstraction at work.
This rule enforces that programmers should make their code read like well written prose by naming parts
of their code perfectly. With such good naming, a programmer will never need to resort to comments or unnecessary
doc strings.
Below is a code snippet from a software system. Would you make sense of it without any explanation?
Bad 😠
from typing import List
def f(a : List[List[int]])->List[List[int]]:
return [i for i in a if i[1] == 0]Better 😃
from typing import List
Orders = List[Order]
def get_pending_orders(orders : Orders)-> Orders:
return [order for order in orders if order.is_pending()]WIP.
- Add Changelog
- Add back to top links
- Add Additional Templates w/ Examples
- Add "components" document to easily copy & paste sections of the readme
- Multi-language Support
- Portuguese
- Spanish
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE.txt for more information.
Vitor Meriat is a computer scientist who is passionate about creating software that will positively change the world we live in.
Use this space to list resources you find helpful and would like to give credit to. I've included a few of my favorites to kick things off!