**My Learnings/jottings on software Engineering Practices**
Software engineering preactices are a crucial part of the software development process.
These are practices that every developers should learn and apply in their day to day coding activities. Every code should be:
This makes code to be reused and shared among other developers. It helps reliability and easier maintenance of source code.
A *clean* code is simple, concise and readable
A *Modular code* is one that is logically broken down into smaller parts; as function and modules.
It makes code more organised, modular and reusable.
A *Module* is a file that allow code to be reused by encapsulating them into files that can be imported into other files.
This shows the efficiency of code in production servers.
- Be descriptive and imply type
- Be consistent but clearly differentiate - E.g. age_list and age is easier to differentiate than ages and age.
- Avoid abbreviations and especially single letters
- Long names != descriptive names
- Organize your code with consistent indentation
- Separate sections with blank lines to keep your code well organized and readable.
- Try to limit your lines to around 79 characters, which is the guideline given in the PEP 8 style guide.
- DRY (Don't Repeat Yourself)
- Abstract out logic to improve readability
- Minimize the number of entities (functions, classes, modules, etc.)
- Functions should do one thing
- Arbitrary variable names can be more effective in certain functions
- Try to use fewer than three arguments per function
Optimizing code to be more efficient can mean making it:
- Execute faster
- Take up less space in memory/storage
Documentation is an additional text or illustrated information that comes with or is embedded in the code of software.
Helpful for clarifying complex parts of code, making your code easier to navigate, and quickly conveying how and why different components of your program are used.
Several types of documentation can be added at different levels of your program:
- In-line Comments - line level
- Docstrings - module and function level
- Project Documentation - project level
In-Line Comments:
- It is used to document the major steps of complex code to help readers follow.
- Comments are valuable for explaining where code cannot.
Docstrings:
Docstrings are valuable pieces of documentation that explain the functionality of any function or module in code. Ideally, each function should always have a docstring.
Docstrings are surrounded by triple quotes. The first line of the docstring is a brief explanation of the function's purpose.
Docstrings can be
- one line, or
- multi line
Project Documentation
Project documentation is essential for getting others to understand why and how your code is relevant to them, whether they are potentials users of your project or developers who may contribute to your code. A great first step in project documentation is your README file. It will often be the first interaction most users will have with your project.
Version Control helps to keep track of changes in code. This is a very useful tool that helps developers switch to different versions as they code along. The most used version control today is git.
Every code should be tested before it is being deployed.
For more info, see Ned Batchelder slide here and video here
Testing helps to catch errors and faulty conclusions before they make any major impact. Proper testing is necessary to avoid unexpected surprises and have confidence in results.
Testing should be done in a way that is repeatable and automated
In software testing, some terms easily come to mind:
It is a development process where developers write tests for tasks before writing the code to implement those tasks.
Unit Testing include test that covers a “unit” of code, usually a single function, independently from the rest of the program.
Unit tests has several benefits:
- They are isolated from the rest of the program/code
- They do not depend on other part of source code/program
- They don't require acces to databases, and other external sources of information
For python, pytest is the tool used for unit testing. pytest is a framework that makes building simple and scalable tests easy. To start with, see here
To use pytest:
- Create a test file starting with test_
- Define unit test functions that start with test_ inside the test file
- Enter pytest into your terminal in the directory of your test file and it will detect these tests for you!
PS: in the test output, periods represent successful unit tests and F's represent failed unit tests.
To show that all the parts of a program work with each other properly, communicating
and transferring data between them correctly, integration tests are used.
Integration testing exercises two or more parts of an application at once, including the interactions between the parts, to determine if they function as intended.
Read more here and here for more info.
Logging is valuable for understanding the events that occur while running code.
It is the process of recording messages to describe events that have occurred while running your software.
- Be professional and clear
- Be concise and use normal capitalization
- Choose the appropriate level for logging
- DEBUG - level you would use for anything that happens in the program.
- ERROR - level to record any error that occurs
- INFO - level to record all actions that are user-driven or system specific, such as regularly scheduled operations
- Provide any useful information
The goal of code review isn't to make all code follow one's personal preferences, but a standard of quality for the whole team.
Cide review helps to:
- catch errors
- ensure reliability
- check that standards are met
- share knowledge among the team
To review a code, there are a few questions that needs to be asked:
- Is the code clean and modular?
- Is the code efficient?
- Is documentation effective?
- Is the code well tested?
- Is the logging effective?
And lastly, to conduct code review:
- Use a code linter
- Explain issues and make suggestions
- Keep your comments objective
- Provide code examples
source: udacity