In the previous chapter, Contribution Guidelines, we learned how to submit a "Pull Request" to share your work with the community.
However, just because your code works doesn't mean it is ready to be shared. Imagine writing a beautiful poem but ignoring all punctuation and capitalization. It would be very hard to read!
In programming, we have "Grammar Rules" called Code Style. This chapter explains the specific style rules for ML-For-Beginners and how to automatically check if your code follows them.
In an open-source project, code is read by humans 10 times more often than it is run by computers. If 50 different contributors write code in 50 different styles, the project becomes a messy patchwork that is impossible to maintain.
The Goal: You have written a Python function to calculate pumpkin prices. It works perfectly, but the indentation is uneven, and you named your variables x and y.
The Problem: The project maintainers reject your Pull Request because they can't understand what x does.
The Solution: You need to apply Linting. This is the process of using a tool to smooth out your code, fix the spacing, and rename variables to match the project's standard "Uniform."
We use different "Uniforms" for different languages.
PEP 8 is the official style guide for Python code. It is a long list of rules about how code should look.
snake_case (e.g., pumpkin_price) for variables, not CamelCase.x + y, not x+y).For the Quiz App (covered in Quiz Application Development), we use a tool called ESLint. Unlike Python's PEP 8 (which is often a guideline), ESLint runs inside the code editor and shouts at you (with red squiggly lines) if you break a rule.
Documentation must be readable. We use standard Markdown rules:
#) should have a space after the hash.Let's look at how to fix "Ugly Code" to match our guidelines.
Bad Code (Hard to read):
def Calc(x,y):
# No spaces, bad indentation, bad name
return x*y+100
Good Code (PEP 8 Compliant):
def calculate_price(quantity, unit_price):
# 4 spaces indentation, clear names
base_cost = quantity * unit_price
return base_cost + 100
Explanation: The logic is the same, but the second version tells a story. We use snake_case for the function name and add spaces around the * and +.
In the Quiz App, we can use the tools we installed in Quiz Application Development to fix errors automatically.
The Command:
Open your terminal in the quiz-app folder and run:
# Ask the computer to find and fix style errors
npm run lint
Output:
DONE No lint errors found!
Explanation: If you had missing semicolons or messy spacing, this command would either fix them for you or tell you exactly which line number to fix manually.
How do we ensure that every contributor follows these rules? We don't trust humans to remember them. We use robots.
When you push code to GitHub (as learned in Contribution Guidelines), a "Workflow" triggers.
How does the robot know the rules? It reads configuration files hidden in the root of the project folders.
For JavaScript (.eslintrc.js):
This file tells the linter which rules to enforce.
// Inside quiz-app/.eslintrc.js
module.exports = {
root: true,
rules: {
// "warn" means tell me, but don't break the build
'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
// "error" means stop everything if this happens
'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off'
}
}
Explanation: This file is the rulebook. It defines what counts as a "crime" in code style. For example, leaving debugger commands in your code is forbidden in production.
For Markdown (.markdownlint.json):
Though not always visible, many projects use a JSON file to enforce document structure.
{
"default": true,
"MD013": false,
"MD033": false
}
Explanation: MD013 is a rule that says "Lines cannot be too long." We set it to false (turn it off) because sometimes paragraphs need to be long.
In this chapter, we learned that Code Style is about communication, not just code.
this_one, 4 spaces indent).npm run lint).Now you have the environment, the workflow, and the style guidelines. But what happens when you follow all the rules and the code still doesn't work?
Generated by Code IQ