diff --git a/docs/PROGRAMMING_TIPS.md b/docs/PROGRAMMING_TIPS.md new file mode 100644 index 0000000000..9fd443f3f4 --- /dev/null +++ b/docs/PROGRAMMING_TIPS.md @@ -0,0 +1,39 @@ +# Programming Tips + +## Naming A Function + +Picking good function names is an essential part of writing good code. +Consider the following recommendations when you name your function. + +### Choose meaningful function names + +When you name your function, you should be clear on what it does. +For example, the function `get(studentId, subject)` doesn't have a meaningful function name, and therefore, it is not clear what it does. +It might be getting the student's subject grade or getting their enrollment status. +A better name would be `getStudentGrade(studentId, subject)`, as it precisely communicates what the function does. + +### Don't make the function name too long + +Take care not to make a function name too long. +For example, `checkStudentFailOrPassOrMeritOrDistinction(mark)` is an unnecessarily long function name. +The longer the name is, the harder it gets to remember and the more space it takes on the computer screen. + +### Don't make the function name too short + +Conversely, making a function name too short can also confuse readers. +For example, `checkFPMD(mark)` is a bad function name as it isn't immediately obvious what 'FPMD' means. + +### Use the name that everyone understands. + +Your function name should be understandable by everyone who reads your code. +For example, an obscure function name like `DeathStar()` might be amusing to you, but the name doesn't communicate its purpose and can cause confusion for other developers who read your code. + +### Pick one convention for naming operations + +Stick to one convention for naming operations that do the same thing. +For example, if you name the function to get a student's name `getStudentName()`, you should not use a different verb in the function name to get a student's grade (e.g. `retrieveStudentGrade()`). + +### Avoid using the same word for two purposes + +For example, don't keep using `add` when you want to put a group of items into a collection if you already named it on a addition of two numbers. +Use `insert` or `append` instead. diff --git a/docs/config.json b/docs/config.json index 6e18069b6b..2439a919d6 100644 --- a/docs/config.json +++ b/docs/config.json @@ -34,6 +34,13 @@ "path": "docs/ROADMAP.md", "title": "Roadmap & Concept List", "blurb": "Priorities for future development of the JavaScript track" + }, + { + "uuid": "eef6eca6-6ee8-4ab5-a97a-3e8eb7785c7e", + "slug": "tips", + "path": "docs/PROGRAMMING_TIPS.md", + "title": "Programming Tips", + "blurb": "General tips on how to write good code" } ] }