DEV Community: DOREEN ATIENO

Best Practices for Writing Commit Messages and Code Comments

DOREEN ATIENO — Mon, 07 Jul 2025 13:54:54 +0000

Every line of code you write solves a problem.But what if someone else has to understand, fix, or build on that code tomorrow, or even months from now? That’s where your commit messages and code comments become silent allies. They don’t just document your work, they tell the story behind it. They capture the why, not just the what.They transform a code-base from a pile of logic into a living, collaborative space.

In this guide, we’ll walk through simple, practical tips to help you write commit messages that matter and comments that make a difference, so your future self (and your team) will thank you.

Let’s make your code not just functional, but unforgettable.

Writing Good Commit Messages

Why Commit Messages Matter

Commit messages are documentation. They:
a. Explain the intention behind code changes.
b. Help future developers (including yourself) understand the history
c. Make debugging and code reviews easier
d. Improve collaboration and traceability

Format

Use this structure:
<type>: <short summary> [optional body for context]

Common Commit Types

feat Used when Adding a new feature
fix Used when Fixing a bug
refactor Used when Restructuring code without changing behavior
docs Used when Updating documentation
style Used when Code formatting (indentation, spacing)
test Used when Adding or fixing tests
chore Used for Misc tasks like build, CI, config

Writing the Summary

a. Be concise and start with a verb:

    fix: handle null user on login
    feat: add dark mode toggle

Limit to 50 characters if possible

b. Use present tense (as if describing what this commit does)
Example Messages

    feat: implement user login endpoint
    Added JWT-based authentication with login and token generation.

    fix: correct typo in signup form validation error
    refactor: extract database logic into separate package

Writing Clear Code Comments

Why Comment?

a. Explain why, not just what

b. Clarify complex logic, not the obvious

c. Help future readers maintain or extend the code

Commenting Best Practices

Avoid obvious comments

     ❌ i++ // increment i
     ✅ i++ // move to the next user in the list

Use comments to explain “why”, not “what”

     ❌ // fetch user
     ✅ // Fetch user so we can prefill the edit form

Document assumptions, edge cases, and decisions

     // We retry 3 times to handle transient network failures
     for i := 0; i < 3; i++ {
     ...
     }

Prefer self-explanatory code over excessive comments

Rename variables or functions if a comment feels necessary

 // Bad
 let x = 10; // maximum retries
 // Better
 let maxRetries = 10;

Use TODO/FIXME tags sparingly and consistently

     # TODO: Refactor this to async in next release

What to Avoid

a. Vague commit messages like changes, update, or fix bug
b. Over-commenting every line
c. Outdated comments - update or remove them as code changes
d. Jokes or sarcasm in comments (yes, it happens)

Final Tips

a. Use version control tools (git log, git blame) as communication history
b. Treat your commit history like documentation
c. Imagine someone else reading your code months later, what would they need?

Conclusion

Great code is more than just working code, it's communicative, thoughtful, and human-friendly. Every commit message you write is a window into your decision-making. Every comment you leave is a helping hand to your future self or another developer.

So don’t just write code, tell the story behind it. Be the kind of developer others thank when digging through version history or deciphering a complex logic flow.

Let your commits document your journey.
Let your comments guide the reader through your thinking.
And let your code-base be one that’s not only powerful, but understandable, maintainable, and admired.

Now go write like someone will read it, because they will.

Getting Started with Django: A Beginner's Guide to Web Development.

DOREEN ATIENO — Mon, 30 Jun 2025 20:19:39 +0000

Django: The Web Developer's Blueprint

Imagine you're building a house. You could start from scratch, cutting every piece of wood and mixing every batch of concrete. Or you could use a proven blueprint with pre-made components that fit together perfectly.

Django is that blueprint for web development.

Django is a high-level Python web framework that follows the "batteries-included" philosophy. This means it comes with everything you need to build a production-ready web application — from user authentication to database management, all built-in and ready to use.

Whether you want to build a blog, an e-commerce site, a social network, or a business application, Django provides the tools and structure to make it happen efficiently and securely.

Understanding Django's Architecture: The MVT Pattern

Django follows the Model-View-Template (MVT) pattern, which is Django's interpretation of the popular MVC (Model-View-Controller) pattern. Understanding this architecture is crucial to becoming proficient with Django.

What is MVT?

MVT separates your application into three distinct layers, each with specific responsibilities:

1. Models – Your Data Layer

Models represent your data structure and business logic. They define:

Database tables and their relationships
Data validation rules and constraints
Business logic methods that operate on your data
How data is stored, retrieved, and manipulated

Think of models as the blueprint for your database.

Example:

If you're building a blog, your models might include:

User (for authors and readers)
Post (for blog articles)
Comment (for reader feedback)
Category (for organizing posts)

2. Views – Your Logic Layer

Views handle the business logic of your application. They:

Process user requests (GET, POST, etc.)
Interact with models to retrieve or modify data
Apply business rules and validation
Prepare data for presentation
Return responses to users

Views are where the "thinking" happens in your application.

Example:

A view might:

Receive a request to display a blog post
Fetch the post data from the database
Check if the user has permission to view it
Prepare the data for the template
Return the rendered page

3. Templates – Your Presentation Layer

Templates define how your data is presented to users. They:

Display data in a user-friendly format
Handle the visual presentation of your application
Include conditional logic for dynamic content
Manage the HTML structure and styling

Templates are responsible for the "look and feel" of your application.

Example:

A template might:

Display a blog post with proper formatting
Show different content for logged-in vs. anonymous users
Include navigation menus and footers
Handle responsive design for different screen sizes

How MVT Works Together

Here's the typical flow of a Django application:

User makes a request

(e.g., visits a page or submits a form)
URL routing directs the request to the appropriate view
View processes the request and interacts with models as needed
Models handle data operations

(e.g., database queries, validation, etc.)
View prepares data and selects a template
Template renders the response using the provided data
Response is sent back to the user

Benefits of This Separation of Concerns

This structure makes your Django code:

Maintainable: Changes to one layer don't necessarily affect others
Testable: You can test each layer independently
Reusable: Components can be reused across different parts of your application
Scalable: You can optimize each layer separately as your application grows

Setting Up Your Django Development Environment

Step 1: Install Python

Django requires Python 3.8 or higher.

To check your Python version, run the following command:

python --version
# or
python3 --version

If you don't have Python installed, download it from python.org. Make sure to check "Add Python to PATH" during installation on Windows.

Step 2: Create a Virtual Environment

Virtual environments are essential for Python development.
They keep your project dependencies isolated from other projects and your system Python installation.

# Create a new directory for your project
mkdir my_first_django_project
cd my_first_django_project
# Create a virtual environment
python -m venv venv
# Activate the virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

You'll know the virtual environment is active when you see (venv) at the beginning of your command prompt.

Step 3: Install Django

With your virtual environment activated, install Django:

pip install django

# Verify the installation
python -m django --version

Step 4: Create Your First Django Project

# Create a new Django project
django-admin startproject myproject
cd myproject

# Start the development server
python manage.py runserver

Visit http://localhost:8000/ in your browser. You should see the Django welcome page - congratulations! You've successfully set up Django.

Creating Your First Django App

Django projects are composed of multiple "apps" — each handling a specific feature or functionality. This modular approach makes your code organized and reusable.

Step 1: Create an App

Run the following command in your terminal:

python manage.py startapp blog

This creates a new directory structure:

blog/
├── __init__.py
├── admin.py
├── apps.py
├── models.py
├── tests.py
├── urls.py
└── views.py

Step 2: Register Your App

Open myproject/settings.py and add your app to the INSTALLED_APPS list:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'blog',  # Add your app here
]

Best Practices for Django Development

Code Organization

Keep apps focused on specific functionality
Use meaningful names for models, views, and templates
Follow Django's naming conventions
Organize your project structure logically

Performance

Use database indexes for frequently queried fields
Optimize database queries using select_related and prefetch_related
Cache expensive operations
Use pagination for large datasets

Security

Always validate user input
Use Django's built-in security features
Keep dependencies updated
Follow the principle of least privilege

Testing

Write tests for all your models, views, and forms
Use test-driven development (TDD) when possible
Test both happy paths and edge cases
Maintain good test coverage

Conclusion: Your Django Journey Begins

Django is a powerful, flexible framework that can handle projects of any size. From simple blogs to complex enterprise applications, Django provides the tools and structure you need to build robust web applications.

The key to mastering Django is understanding the MVT pattern and how the different components work together. Start with simple projects, experiment with different features, and gradually build up to more complex applications.

Structs and Methods in Go: A Beginner-Friendly Guide

DOREEN ATIENO — Wed, 04 Dec 2024 05:30:44 +0000

Go (or Golang) is known for its simplicity and efficiency. Structs and methods are foundational concepts in Go that help you organize and manage data effectively. This guide will take you through the basics of structs, methods, and how to use them systematically. Ensure you have go installed in your machine, use the right package and correct imports for you to test the functions.

Understanding Structs in Go

What is a Struct?
I understand struct in Go as a composite data type that groups together variables (fields) under a single name. It is particularly useful for representing more complex data structures. While it serves a role similar to classes in object-oriented programming languages, it does so in a lightweight, straightforward manner without methods like inheritance.

Defining Struct
A struct is defined using the type keyword followed by the struct name(User) and the fields enclosed in curly braces {}.
Each field has a name and a type. For example:

type User struct {
    ID       int
    Name     string
    Email    string
    IsActive bool
}

ID is of type int.
Name and Email are of type string.
IsActive is of type bool.
Fields like ID, Name, Email, and IsActive are capitalized to make them exportable. This means they can be accessed from outside the package.
If a field starts with a lowercase letter, it is unexported and cannot be accessed outside the package where it is defined.

Struct Initialization in Go
Structs in Go can be initialized using named fields or unnamed fields. Let’s explore the differences, advantages, and potential pitfalls of both approaches.

1. Named Fields
When initializing a struct using named fields, you explicitly specify the name of each field along with its value.
Example:

user := User{ 
ID: 1, 
Name: "Doreen", 
Email: "doreen@example.com", 
IsActive: true, 
}

Advantages of Named Fields:
1. Readability:
Each field is clearly labeled with its name, making the code easier to read and understand.
Example: ID: 1 directly shows that the field ID is being assigned the value 1.

2. Order Independence:
The fields can be listed in any order, regardless of how they are defined in the struct.
Example:

user := User{ 
Name: "Doreen", 
IsActive: true, 
Email: "doreen@example.com", 
ID: 1, 
}

3. Safety:
Reduces the chance of assigning values to the wrong fields.
Example:
If you switch the order of ID and Name, the program will still work as intended because the fields are explicitly named.

4. Best Use Cases:
When a struct has many fields, especially of the same type (e.g., multiple strings or integers).
When you want to make your code self-documenting.

2. Unnamed Fields
When initializing a struct using unnamed fields, you omit the field names and provide values in the exact order the fields are defined in the struct.
Example:

user := User{1, "Doreen", "doreen@example.com", true}

Advantages of Unnamed Fields:
Conciseness:
It requires less typing and results in shorter code.

Disadvantages of Unnamed Fields:
1. Order Dependency:
The values must appear in the exact order in which the fields are defined in the struct. If the order changes, it can lead to subtle bugs or incorrect data assignment.
Example:

user := User{"Doreen", 1, "doreen@example.com", true} // This will cause a type mismatch error.

2. Reduced Readability:
Without field names, it’s harder to immediately understand what each value represents, especially if the struct has multiple fields of the same type.
Example:

user := User{1, "Doreen", "doreen@example.com", true}

At a glance, it might not be clear which value corresponds to ID, Name, Email, or IsActive.

Which One Should You Use?
Whenever I decide to use a struct to tackle a problem, I lean toward using named fields for clarity and maintainability. This is especially important in production code or collaborative projects, where readability and reducing errors are key.

I might consider using unnamed fields only if the struct is very small, the order of fields is obvious, and the context is extremely clear. Otherwise, named fields provide a safer and more reliable approach.

Default Values in Go Structs
In Go, when you create a struct instance without specifying values for all the fields, the default values (or "zero values") of the respective types are automatically assigned to the omitted fields. This behavior ensures that structs are always initialized, even if you don’t explicitly set all the fields.

What Are Default (Zero) Values?
Zero values represent the "default state" of each data type in Go. I have several examples that will help you understand zero values.

Example 1: Omitted Fields in Struct Initialization
Consider the following struct:

type User struct { 
ID int 
Name string 
Email string 
IsActive bool 
}

If you initialize an instance and omit some fields:

user := User{
    ID: 10,     // ID is initialized
    Name:  "Doreen",  // Name is initialized
    // Email and IsActive are omitted
}

The omitted fields (Email and IsActive) take their zero values:
Email (string): "" (empty string)
IsActive (bool): false

fmt.Println(user) // {10 Doreen  false}

Example 2: Empty Struct Initialization
If you don’t initialize any fields at all:

user := User{}
fmt.Println(user)

All fields will have their zero values:
ID → 0 (default for int)
Name → "" (default for string)
Email → "" (default for string)
IsActive → false (default for bool)

Output:

{0   false}

Example 3: Partial Initialization with Positional Values
If you use unnamed fields but don’t provide values for all fields, the omitted fields will still be set to their zero values:

user := User{1, "Johns"}
fmt.Println(user)

Output:

{1 Johns  false}

Here:
Email (string) defaults to "".
IsActive (bool) defaults to false.

Why Are Zero Values Useful?
1. Safety:
Go ensures that all fields are initialized, so there are no uninitialized fields causing undefined behavior.

2. Simplicity:
You don’t have to explicitly initialize every field if you’re okay with some fields having default values.

3. Convenience in Prototyping:
When quickly testing or prototyping, you can focus only on the fields you care about.

4. Avoid Reliance on Default Values for Logic
While Go's zero values (default values) are convenient, relying on them for important application logic can lead to subtle bugs and unintended behavior. This happens because the zero value for a type might not adequately represent your intended state or meaning.

Why is it that, Relying on Default Values Can Be Problematic?
1. Lack of Clarity:
If a field is left uninitialized and automatically takes its zero value, it can be unclear whether the zero value was explicitly set by the programmer or simply defaulted. This ambiguity can make debugging difficult.

2. Unintended State:
If your code assumes a field is initialized with a meaningful value and processes the zero value instead, it could cause incorrect logic or results.

3. Logic Errors:
Using default values might pass unnoticed in validation checks or business logic. For example, if 0 is a valid input for an int field, you won’t know if it was explicitly set or is the default.

Example of the Problem
Imagine a struct for a user profile:

type User struct {
    ID      int
    Name    string
    Email   string
    IsActive bool
}

Take it this way,suppose you write a logic that relies on IsActive to determine if a user is active:

func CheckActive(user User) {
    if user.IsActive {
        fmt.Println("User is active!")
    } else {
        fmt.Println("User is inactive.")
    }
}

And you accidentally leave IsActive uninitialized when creating a user:

newUser := User{
    ID: 1,
    Name:  "Doreen",
    Email: "doreen@example.com",
    // IsActive is omitted
}
CheckActive(newUser)

Output:

User is inactive.

The logic assumes that IsActive = false meaning the user is inactive, but the field wasn’t explicitly initialized—it defaulted to false. This could lead to misclassification of users.

Best Practices to Avoid Issues
1. Explicit Initialization:
Always initialize fields explicitly if their value is meaningful to your logic.

newUser := User{
    ID:     1,
    Name:   "Doreen",
    Email:  "doreen@example.com",
    IsActive: true, // Explicitly set
}

2. Use Pointers for Optional Fields:
If a field is optional or its absence is meaningful, use a pointer (*type) instead of relying on its zero value. This makes it clear whether a value was intentionally set.

type User struct {
    ID      int
    Name    string
    Email   string
    IsActive *bool
}

isActive := true
newUser := User{
    ID:     1,
    Name:   "Doreen",
    Email:  "doreen@example.com",
    IsActive: &isActive, // Explicitly set
}

In this case, if IsActive is nil, you know it was never set since we are taking its dereferenced value.

3. Custom Default Values:
Define custom "default" values during struct initialization by using constructor functions.

func NewUser(id int, name, email string) User {
    return User{
        ID:     id,
        Name:   name,
        Email:  email,
        IsActive: false, // Explicit default value
    }
}

user := NewUser(1, "Johns", "johns@example.com")
fmt.Println(user.IsActive) // Outputs: false

In this case IsActive is false because it is omitted so it automatically takes the default value which is false.

4. Validation Logic:
Include validation checks to ensure fields are initialized with appropriate values before use.

func ValidateUser(user User) error {
    if user.Name == "" {
        return fmt.Errorf("Name cannot be empty")
    }
    if user.Email == "" {
        return fmt.Errorf("Email cannot be empty")
    }
    return nil
}

In this case, empty Name and Email is not accepted.

Why Use Structs in Go?
There are a number of features and advantages that structs come with that has, is and will always make me choose structs. Here's why structs are so valuable:

1. Organizing Related Data
Structs group related fields (variables) into a single logical unit. This makes your code more readable and manageable.
Instead of managing multiple variables, you can handle them as a single Struct (User).
Instead of initializing all these variables,

var ID int
var Name string
var Email string
var IsActive bool

you can always group them in one struct.

type User struct {
    ID      int
    Name    string
    Email   string
    IsActive bool
}

2. Reusability
Structs enable you to define reusable types that can be used across different parts of your program.
Example:

type Product struct {
    ID      int
    Name    string
    Price   float64
}

With the above struct you can create multiple product instances without redefining fields each time:

product1 := Product{1, "Laptop", 1200.50}
product2 := Product{2, "Smartphone", 800.00}

3. Customization with Methods
Structs can have methods attached to them, allowing you to define custom behaviors for struct instances.
Take a chill pill we are about to explore on methods.
Here is an example to make you eager.
Example:

type User struct {
    Name     string
    IsActive bool
}

func (u User) Greet() string {
    return "Hello, " + u.Name
}

func main() {
    user := User{Name: "Doreen", IsActive: true}
    fmt.Println(user.Greet()) // Output: Hello, Doreen
}

This enhances the struct’s functionality and encapsulates related behaviors.

4. Encapsulation
Structs allow you to control access to their fields using export rules:
Exported Fields: Start with an uppercase letter and are accessible outside their package.
Unexported Fields: Start with a lowercase letter and are private to the package.

Example:

type User struct {
    ID      int
    name    string // private field
    Email   string // public field
}

5. Flexible and Extensible
Structs can be extended with composition, a common pattern in Go where you embed one struct inside another.

Example:

type Address struct {
    City  string
    State string
}

type User struct {
    Name    string
    Address // Embedded struct
}

func main() {
    user := User{
        Name: "Doreen",
        Address: Address{
            City:  "Nairobi",
            State: "Kenya",
        },
    }
    fmt.Println(user.City) // Output: Nairobi
}

6. Efficient Memory Representation
Structs provide a compact and efficient way to group fields in memory. They use less overhead compared to alternatives like maps or slices for organizing data.

7. Foundation for Object-Oriented Design
Although Go is not an object-oriented language, structs form the backbone of its type system. You can:
Simulate classes by attaching methods to structs.
Use interfaces to define shared behaviors between structs.

8. Essential for JSON, XML, and Other Formats
Structs are often used to work with data serialization formats like JSON, XML, or databases. Go’s encoding packages (like encoding/json) can easily marshal and unmarshal structs.
Example: JSON Serialization

import "encoding/json"

type User struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

func main() {
    user := User{Name: "Doreen", Email: "doreen@example.com"}
    jsonData, _ := json.Marshal(user)
    fmt.Println(string(jsonData)) // Output: {"name":"Doreen","email":"doreen@example.com"}
}

9. Better Type Safety
Structs provide a more type-safe way to handle related data compared to alternatives like maps, where keys and values can have any type. With structs, field types are fixed, and the compiler can catch errors.
Example:

With a map:

data := map[string]interface{}{"ID": 1, "Name": "Doreen"}

With struct

type User struct {
    ID   int
    Name string
}

The compiler ensures that ID is always an int and Name is always a string.

Customization with Methods in Go Structs

In Go, you can attach methods to structs to define behaviors or actions related to the struct. This makes your code more organized, readable, and modular. It allows structs to encapsulate both data (fields) and related functionality (methods), mimicking the behavior of classes in object-oriented programming.

What is a Method?
A method in Go is simply a function that has a receiver. The receiver specifies the struct (or other type) the method is associated with. The method can then operate on the struct's fields.
Syntax of a Method

func (receiver ReceiverType) MethodName(parameters) returnType {
    // Method body
}

Receiver: The variable name and type (e.g., (u User)) that the method is attached to.
MethodName: The name of the method.
Parameters: The inputs to the method (optional).
ReturnType: The type of value the method returns (optional).

Example: Methods on a Struct

type User struct {
    Name    string
    IsActive bool
}

// Method attached to User struct
func (u User) Greet() string {
    return "Hello, " + u.Name
}

Receiver: (u User) associates the method Greet with the User struct.
Purpose: The method generates a greeting message using the Name field of the struct.
Using the Method

func main() {
    user := User{Name: "Doreen", IsActive: true}
    fmt.Println(user.Greet()) // Output: Hello, Doreen
}

Receiver Types: Value vs. Pointer
Methods can have either a value receiver or a pointer receiver, depending on how you want the method to interact with the struct's data.
1. Value Receiver
A copy of the struct is passed to the method.
Changes made to the struct within the method do not affect the original instance.
You can use this when the method does not modify the struct or when the struct is small.

func (u User) DisplayStatus() {
    u.IsActive = false // This modifies a copy
    fmt.Println("Inside method:", u.IsActive) // false
}

func main() {
    user := User{Name: "Doreen", IsActive: true}
    user.DisplayStatus()
    fmt.Println("Outside method:", user.IsActive) // true
}

2. Pointer Receiver
Here a pointer to the struct is passed to the method.
Changes made within the method affect the original struct.
You can use this when the method modifies the struct or the struct is large.

func (u *User) Deactivate() {
    u.IsActive = false // Modifies the original instance
}

func main() {
    user := User{Name: "Doreen", IsActive: true}
    user.Deactivate()
    fmt.Println("User status:", user.IsActive) // false
}

Methods with Parameters and Return Values
Methods can take additional parameters and return values like regular functions.
Example: Calculating Discount

type Product struct {
    Name  string
    Price float64
}

// Method to calculate discounted price
func (p Product) Discount(rate float64) float64 {
    return p.Price * (1 - rate)
}

func main() {
    product := Product{Name: "Laptop", Price: 1000}
    fmt.Println("Discounted Price:", product.Discount(0.1)) // 900
}

Encapsulation and Abstraction
Methods allow you to encapsulate complex logic inside structs, exposing only necessary details to the user.
Example: Encapsulating Validation Logic

type User struct {
    Name  string
    Email string
}

func (u User) IsValidEmail() bool {
    return strings.Contains(u.Email, "@")
}

func main() {
    user := User{Name: "Johns", Email: "johns@example.com"}
    fmt.Println("Valid email:", user.IsValidEmail()) // true
}

The logic for validating the email is encapsulated in the IsValidEmail method, keeping it separate from other parts of the code.

Chaining Methods
Since methods can return the struct itself (or a pointer to it), you can chain multiple methods together for more concise and readable code.
Example: Chaining User Updates

type User struct {
    Name  string
    Email string
}

func (u *User) SetName(name string) *User {
    u.Name = name
    return u
}

func (u *User) SetEmail(email string) *User {
    u.Email = email
    return u
}

func main() {
    user := &User{}
    user.SetName("Doreen").SetEmail("doreen@example.com")
    fmt.Println(user) // &{Doreen doreen@example.com}
}

Benefits of Methods in Structs
Code Organization: Groups related data (fields) and functionality (methods) together.
Readability: Methods clearly express the actions or behaviors of a struct.
Encapsulation: Keeps implementation details hidden and exposes only necessary functionality.
Reusability: Methods can operate on struct instances in various parts of the program.
Extensibility: Easily add new behaviors without altering external code.
By attaching methods to structs, you can make your Go programs more modular, maintainable, and expressive!

Conclusion

Structs in Go are powerful, flexible, and integral to writing clean, efficient, and organized code. They are the go-to choice when you need to represent real-world entities, manage data, or implement object-oriented principles. By mastering structs, you can create scalable and maintainable Go applications.
By attaching methods to structs, you can make your Go programs more modular, maintainable, and expressive!