Skip to content

Commit

Permalink
Add Instructions, base README
Browse files Browse the repository at this point in the history
  • Loading branch information
Karn committed Dec 13, 2019
1 parent cf7399f commit 3c29273
Show file tree
Hide file tree
Showing 6 changed files with 86 additions and 1 deletion.
25 changes: 25 additions & 0 deletions CODING_INSTRUCTIONS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Coding Instructions

- If we do not provide sample input/output in the problem, make reasonable assumptions. If we do, they are still just guidelines, so feel free to make reasonable changes.

- Your goal isn't to pass some automated test-case checker: instead, it is to build something that will be __intuitively useful__ to other people, and so use your best judgement.

- Please abide by the [style guide for your preferred language](https://google.github.io/styleguide/).

- Why? Code is written only once, but read many many times, and so we want to optimize for that. If everyone follows the same conventions while writing code, it makes other people's code look like your own, and therefore, easier to understand.

- A good analogy is that writing code without following a style guide is like using texting language in professional communication ("whr r u", instead of "Where are you?"). No one will take you seriously. Which is why this needs to become a habit ASAP.

- Please create useful variable / function names.

- When you're working with larger codebases, no one has the time to read all the code. Which means that you have to infer reasonable behavior based purely on names. And using proper descriptive variable / function names is the first step in making that possible. Not doing so would mean that other engineers cannot trust your code, which is not a situation you want to put yourself in.

- Ask yourself: Is it possible to figure out what this variable contains based on just the name? If no, then it means that your variable doesn't have a good name. Avoid abbreviations if possible, since they introduce ambiguity, forcing the reader to figure out what you meant based on context (eg - `cmp` could mean `compare`, `comparator`, `compulsory`, etc). In almost all cases, `temp` (along with all its variants) is a bad name, because it tells me nothing about what it contains.

- Similarly: Given just the function name and appropriate context, if you ask someone else to implement this function, will their code match yours (adjusting for minor differences)? If no, then your function doesn't have a good name. One important observation here is to never do something inside a function that isn't expected by just reading the name (eg - your `check` function should never print anything).

- Please write well-structured code with clean abstractions.

- What does that mean? The person reading your code should know how it works based purely on an understanding of the problem, and the API you provide. The fact that one does not have to read the internals of your code to understand it, is nice consequence of making the reasonable choice at every point. And this is extremely valuable while debugging complex systems.

- Additionally, make sure that your code is resuable: that it solves more than just the exact problem you are working on right now. In real life, requirements are always changing, and you want to make sure you can handle that with minimal effort. To simulate that, I will always evaluate your code at a higher standard than the problem statement given to you.
59 changes: 58 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,59 @@
# Git-Freeze
A three-week-long dev-a-thon.

# ![Git Freeze Spread](assets/gitfreeze.jpg)

<p align="center">
<a href='https://discord.gg/Qxz2A5s'><img src='https://img.shields.io/badge/Connect_on-Discord-3AAE84.svg?longCache=true&amp;style=for-the-badge' alt='discord_badge' referrerPolicy='no-referrer' /></a>
<a href='https://kutt.it/ietfb'><img src='https://img.shields.io/badge/Follow_On-Facebook-3C5898.svg?longCache=true&amp;style=for-the-badge' alt='fb_badge' referrerPolicy='no-referrer' /></a>
<a href='http://iet.bitmesra.ac.in/'><img src='https://img.shields.io/badge/Visit_On-Website-CF000F.svg?longCache=true&amp;style=for-the-badge' alt='website_badge' referrerPolicy='no-referrer' /></a>
</p>



Welcome to Git Freeze! Each week we will be providing you with a small project idea or let’s say a real life problem statement along with an extensive list of resources that'll help you gain the skills required for the project. You will have one week to learn the relevant technologies and solve the problem. Make sure you read and follow the [coding instructions](./CODING_INSTRUCTIONS.md). If you have any doubts, you can reach out to us anytime on [discord](https://discord.gg/Qxz2A5s). Let's get to some specifics.

- [First Steps](#first-steps)
- [Attempting Problems](#attempting-problems)
- [General Tips](#general-tips)
- [Results & Prizes](#results--prizes)

## First Steps

- You'll have to use [Git](https://www.youtube.com/watch?v=uhtzxPU7Bz0) & [Github](https://www.youtube.com/watch?v=w3jLJU7DT5E) for [version control](https://git-scm.com/video/what-is-version-control). Here are some resources to get you started:
- [Code School's tryGit](https://try.github.io/)
- [TheNewBoston's Git Tutorial](https://www.youtube.com/playlist?list=PL6gx4Cwl9DGAKWClAD_iKpNC0bGHxGhcx)
- [Github's Github Learning Lab](https://www.youtube.com/watch?v=9S0p8YMQzsM)
- [Udacity's Git & Github Course](https://in.udacity.com/course/how-to-use-git-and-github--ud775)
- [Udacity's Github Collaboration Course](https://in.udacity.com/course/github-collaboration--ud456)
- [Learn Git Branching - An interactive way to learn Git](https://learngitbranching.js.org/?demo)

- Make your github account (if you don’t already have one). Avail [github student pack](https://education.github.com/pack) to get amazing student benefits like free services & private repositories. You may use college email-id or semester registration card to avail it. This process generally takes 24 - 48 hours for approval. (Although student pack isn't **required** for participating in Git Freeze, we highly recommend claiming it. After all, it's free!)

## Attempting Problems

On your local machine, prepare the solution in a new folder. Here enable and use git to keep track of your files. Once your solution is prepared do the following:

- Fork this repository.
- Clone your forked repo on your local machine.
- Create a new branch with the following format: `<github-username>/week<num>`, e.g.: `karan/week1`
- Create a directory in the respective week's directory with your github username as the name of the directory.
- Code your solution in that directory only.
- Create a README.md file. It must contain the following:
- How to run? This is very important as we all use different tools so provide a brief description as to how you ran your code in your machine while preparing the solution.
- Softwares / Tools used while making the project.
- What your project does? Describe each and every feature (more or less) of your project.
- Once you feel you have fulfilled the basic requirements, push your code to github and create a pull request.
- After the specified time period, you will be evaluated on the basis of project execution, code quality, ideas and many more parameters.

## General Tips

- A wise guy has said *Conventions Maketh Coder*. So, ensure that you follow coding standards. This makes your code readable and understandable for others **as well as you** at a later point. You can use vigilance as well as editor/ide extensions to assist in this. Here are some coding standards for some popular languages:
- [Python](https://www.python.org/dev/peps/pep-0008/)
- [JavaScript](https://www.w3schools.com/js/js_conventions.asp)
- [C++](https://google.github.io/styleguide/cppguide.html)
- [Java](https://google.github.io/styleguide/javaguide.html)

## Results & Prizes

- Every week, we will select the best attempt at solving the problem. Their code will be added here at the end of the event.
- If you get featured on a problem, you stand to win prizes and more !!
1 change: 1 addition & 0 deletions Week-1/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Incoming Soon
1 change: 1 addition & 0 deletions Week-2/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Incoming Soon
1 change: 1 addition & 0 deletions Week-3/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Incoming Soon
Binary file added assets/gitfreeze.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 3c29273

Please sign in to comment.