clever / dev-handbook Goto Github PK

I think a lot of READMEs could benefit from documenting the limitations of the tool, e.g. "X has been tested with a size N input" or "X does not work for inputs of size greater than N"

To tie together some of the content we're working on it'd be great to have a guide for code reviewing.

@jonahkagan also working on this

Delete branch and deploy

Should cover:

• why version?
• semver!!!
• bump version each time you deploy
• tips by language (e.g. for node, use npm version)

Questions:

• Should we dictate a convention about making separate commits for a version bump?
• Should this be part of the git guide? On one hand, it is part of the workflow. On the other hand, it has to do more with deploying than source control.

@ericavonb + @mohit working on this

The style section doesn't cover more general language-unspecific readability tips. One that comes to mind is variable/function naming.

Off the top of my head, a few good rules:

• avoid one letter variable names, prefer names that use full words or common abbreviations
• avoid general nouns like "data" or "result", prefer specific and accurate nouns
• for functions, avoid general verbs like "do", "get", or "process", prefer more specific verbs or omit the verb entirely

@nathanleiby also working on this

Assessing the effect of code changes on other people/systems

@schimmy and @mohit working on this

@jonahkagan also working on this

@mohit and @ericavonb working on this

Also might be good to elaborate on strategies to avoid this (e.g. git add -p, git commit -v)

many recommendations about committing, but none about pushing

Lots of principles, but no examples

How to write a good README--testing, running locally, explaining what the code does

@azylman + @jonahkagan working on this

working on this with @jefff

@jonahkagan and @azylman working on this