DEV Community: Hannah Williams

Best Practices for Code Documentation: Enhancing Clarity and Collaboration

Hannah Williams — Mon, 11 Sep 2023 09:13:29 +0000

Introduction

Code documentation serves as a vital bridge between developers and their work, offering insights into the logic, purpose, and functionality of a software project. It not only aids the original programmers in understanding and maintaining their codebase but also enables seamless collaboration among team members. This article delves into the significance of documenting code and presents a comprehensive guide to writing clear and effective documentation that fosters improved understanding and collaboration.

The Importance of Code Documentation

Knowledge Transfer: Code documentation is essential for transferring knowledge between developers. New team members can quickly grasp the project's architecture, design choices, and overall flow by referring to well-documented code. It helps prevent a knowledge gap that might otherwise arise due to personnel changes.
Maintenance and Debugging: Code evolves over time, and maintenance is a significant part of a developer's work. Documentation provides context for each function, class, or module, making it easier to identify and rectify bugs or implement updates without disrupting the existing functionality.
Scalability: As projects grow in complexity, maintaining a shared understanding of the codebase becomes increasingly challenging. Clear documentation streamlines the process of scaling a project, enabling developers to build upon existing components without confusion.
Collaboration: In a collaborative environment, multiple developers contribute to the same codebase. Documentation facilitates seamless collaboration by reducing misunderstandings and ensuring that everyone is on the same page regarding the code's purpose and behavior.

Tips for Writing Clear and Effective Documentation

Use Descriptive Comments: Comments should provide an overview of what the code does, not how it does it. Focus on the why and what, explaining the purpose and intended behavior of a piece of code. Avoid redundant comments that simply restate the code itself.
Consistent Formatting: Maintain a consistent formatting style throughout your documentation. Use a clear and easy-to-read font, appropriate indentation, and standard naming conventions for variables, functions, and classes.
Divide and Conquer: Break down your code into logical sections and comment on each section's purpose. This helps readers navigate through the codebase and understand its structure more easily.
Explain Edge Cases: Clearly define how your code handles edge cases, unusual scenarios, and potential errors. This preemptive explanation can save time and prevent confusion when such situations arise in the future.
Provide Examples: Use examples to illustrate how to use different parts of your code. Real-world examples demonstrate the intended usage and can significantly enhance understanding.
Update Documentation Regularly: As the code evolves, keep the documentation up to date. Outdated documentation can lead to confusion and mistakes. Make updating documentation a part of the development process.
Document APIs: For libraries and APIs, clear documentation is paramount. Describe each function's purpose, parameters, return values, and any exceptions it may raise. Well-documented APIs are user-friendly and encourage wider adoption.
Include Diagrams and Flowcharts: Visual aids like diagrams, flowcharts, and UML diagrams can be incredibly helpful in explaining complex algorithms, system architectures, and data flows.
Version Control Integration: Document changes in code using version control system integration. Link documentation updates to specific code changes, making it easier to track the evolution of code and its accompanying explanations.
Seek Peer Review: Just as code benefits from peer review, so does documentation. Have fellow developers review your documentation for clarity, completeness, and accuracy.

Conclusion

Effective code documentation is a foundational aspect of software development that pays dividends in the long run. It enhances communication among developers, eases maintenance and debugging, supports scalability, and fosters collaboration. By following best practices such as using descriptive comments, maintaining consistent formatting, and providing relevant examples, developers can ensure that their codebase remains comprehensible and accessible to both current and future team members. As the landscape of technology continues to evolve, the role of code documentation remains an enduring pillar of successful software engineering.

CSS from a beginners perspective

Hannah Williams — Fri, 11 Nov 2022 19:06:48 +0000

What is CSS?

CSS stands for Cascading Style Sheet, emphasizing the word "style."
While HTML (Hyper Text Markup Language) is a markup language used to build/create websites, CSS is used to describe the visual presentation of the HTML pages, and it is used to "style" the website. It makes your web page look attractive and catchy. In addition, it can boost the user experience on your web page.

NB; You must know HTML to enable you to use CSS.

So, why use CSS?

CSS is used to define/detail the styles for your web pages, such as the design, layout, and display variations for different devices and screen sizes.
Example:

body {
  background-color: lightblue;
}

h1 {
  color: white;
  text-align: center;
}

p {
  font-family: verdana;
  font-size: 20px;
}

Web developers found it challenging when font and color attribute tags were added to the HTML 3.2 specification. Creating large websites where fonts and color information were added to each page became time-consuming and costly.
CSS was created by the World Wide Web Consortium (W3C) to solve this problem.
CSS eliminated the style formatting from the HTML page!

Three ways to use CSS

These are the three types of CSS, and they are listed below:

Inline CSS
Internal or Embedded CSS
External CSS

Inline CSS: Inline CSS is the inclusion of a CSS property in the body section attached to an element. The style attribute is used to specify this type of style within an HTML tag.
Example:

<!DOCTYPE html>
<html>
    <head>
        <title>Inline CSS</title>
    </head>

    <body>
        <p style = "color:purple; font-size:50px;
                font-style:italic; text-align:center;">
            Lianah's Blog
        </p>

    </body>
</html>

The result:

Internal or Embedded CSS: This is used when you want to style a single HTML document uniquely. The CSS set is placed within the HTML in the head section. That is, the CSS is embedded within the HTML file.
Example:

<!DOCTYPE html>
<html>
    <head>
        <title>Internal CSS</title>
        <style>
            .main {
                text-align:center; 
            }
            .LG {
                color:purple;
                font-size:50px;
                font-weight:bold;
            }
            .lianah {
                font-style:bold;
                font-size:20px;
            }
        </style>
    </head>
    <body>
        <div class = "main">
            <div class ="LG">Lianah's Blog</div>

            <div class ="lianah">
                A blog for everything tech
            </div>
        </div>
    </body>
</html>

The result:

External CSS: External CSS is a separate CSS file that only contains style properties via tag attributes (for example, class, id, heading,... etc.). In addition, an external style sheet defines the style for many HTML pages.
To create the external style sheet, you can use any text editor. However, the file must be saved with a .CSS extension and must not contain any HTML code.

Example:
Here is what the separate CSS file (styles.CSS) should contain:

body 
{
    background-color:lavender;
}
.main {
    text-align:center;   
}
.LG {
    color:purple;
    font-size:50px;
    font-weight:bold;
}
#lianah {
    font-style:bold;
    font-size:20px;
}

The HTML file that uses the created external style sheet is shown below.

<!DOCTYPE html>
<html>
    <head>
      <title>External CSS</title>
        <link rel="stylesheet" href="style.css"/>
    </head>

    <body>
        <div class = "main">
            <div class ="LG">Lianah's Blog</div>
            <div id ="lianah">
                A blog for everything tech
            </div>
        </div>
    </body>
</html>

The result:

NB; you can try the codes and edit the color, text, size, and font however you like.

CSS Colors, Fonts, and Sizes

Here, I'll discuss the most used CSS properties: color, font-size, and font-family.

The CSS color property specifies the text color to be used.
The CSS font-size property specifies the text size to be used.
The CSS font-family property specifies the font to be used.

Example:
Below is an example of how to use the CSS color, font-family, and font-size properties.

<!DOCTYPE html>
<html>
<head>
<style>
h1 {
  color: blue;
  font-family: verdana;
  font-size: 300%;

}
p  {
  color: red;
  font-family: courier;
  font-size: 160%;
}
</style>
</head>
<body>

<h1>Lianah's Blog</h1>
<p>A blog for everything tech</p>

</body>
</html>

The result:

I have listed the first three(3), which are the most commonly used properties. Now I will list the other basic properties you should know below.

CSS Border: The CSS border property can create a border around an HTML element.

CSS Padding: This is used to create padding (space) between the text and the border.

CSS Margin: This property creates a margin (space) outside the border.

There are more CSS properties but these are the basic and the most commonly used. I hope this was helpful to you.

Skills you need to become a Web developer

Hannah Williams — Mon, 17 Oct 2022 08:26:07 +0000

Many questions are asked when one wants to start a career in web development, and one of those questions is, "What are the key skills that I'll need for a web development qualification?."

Knowing what a web developer does in their day-to-day job is essential. So, before you can call yourself a web developer and start applying for jobs, here are the following skills you need to master:

Languages

HTML: A markup language used to create websites.
CSS: Used to describe the visual presentation of the HTML pages.
JavaScript: Used to make these pages interactive.

NB; Learning how to use these three core languages is mandatory because it is impossible to have a career in web development without being fluent in them. Also, note that these are not the only programming languages.

Framework

Bootstrap: Allows you to create a responsive and mobile-friendly website that works flawlessly on any device.
React Js: Used to create an interactive user interface and web application efficiently.

NB; Using any of this will be fine.

Design

Figma: Used for interface design
Adobe Xd: A website UI/UX design solution that is quick and powerful.

NB; You can master any of these for your design, or Photoshop and canvas.

By mastering these tools, you have everything you need to become a web developer.

As an extra, you can throw in learning how to use Git and Github

Git: A version control system that allows you to keep track of changes made to your code.
GitHub: Acts as a hosting service for your git repository, it enables collaborative and teamwork projects.

Let me throw in another most asked question, "Do I need a certification to be a web developer?"
This is one of the biggest concerns for people changing careers from other fields to tech. The good news is that no qualification, certificate, or degree is required. As long as you can showcase your work and prove that you have mastered the necessary skills, you can get jobs as web developer.

I hope this article will help you in your journey to become a web developer.

HTML Attributes

Hannah Williams — Mon, 10 Oct 2022 11:07:52 +0000

What is an HTML attribute?

An HTML attribute is a component of the markup language that is used to modify how an HTML element behaves or looks.
For instance, attributes can alter the colour, HTML elements, size, or functionality.

Attributes are used by including them in the first HTML tag:

<tag_name attribute_name="value">Content</tag_name>

The name of the attribute is followed by an equals sign (=) and a value enclosed in quotes. Note that you can often declare a value using a value name and value. For example, you can use the style attribute to change the font-size value name to the value of 40px:

<tag_name style="font-size:40px">This text content will be sized to 40 pixels by the web browser.</tag_name>

Attribute list

Accept;
Types accepted by the server, typically a file type.
Action;
The form would be submitted by the URI of a program that processes it.
Align;
The horizontal alignment of the element is specified.
Alt;
Alternative text in case you can't display an image.
Cite;
It contains a URI pointing to the source or change of the quote.
Class;
is frequently used with CSS to style elements with similar properties.
Codebase;
This attribute specifies the absolute or relative URL of the directory containing the class files referenced by the code attribute.
Data;
Specifies the URL of the resource.
Datetime;
Indicates the element's associated date and time.
Form;
The form that owns the element is indicated.
Href;
a linked resource's URL.
Hreflang;
The language of the linked resource is specified.
ID;
is frequently used with CSS to style a specific element. This attribute's value must be unique.
Inputmode;
suggests the kind of data the user should submit when modifying elements or contents. The attribute can be applied to elements in an editing host or form controls (such as the value of text area elements) (e.g., using a content editable attribute).
Label;
Specifies the element's user-readable title.
List;
Determines a set of pre-defined options to recommend to the user.
Name;
Name of the element. For example, the server uses them to identify the fields in the form submitted.
Style;
Defines CSS styles that will override previously defined styles.
Title;
When hovering over an element, the text will be displayed in a tooltip.
Type;
Defines the type of the element.
Value;
Defines a default value displayed in the element on page load.
NB: these are but a few attributes.

How To Use HTML Attributes
The colour, size, and other characteristics of HTML elements can be changed through HTML attributes. For instance, you can alter a text element's font colour or size using an attribute or an image element's width and height using an attribute.

An example of how a HTML attribute is placed in an opening tag:

<element attribute="property:value;">

Style is a typical attribute that enables you to add style properties to an HTML element. At the same time, it's more typical to style an HTML document using a separate stylesheet.

Using the style attributes we can change multiple properties of an h1 element with the style attributes

<h1 style="font-size:40px;color:green;">This text is 40 pixels and green.</h1>

NB: In HTML, most attributes have two sides, and they are the content attribute and the Interface Definition Language (IDL) attribute.

The content attribute is the attribute as it appears in the content (the HTML code)
Even when an integer should be the expected value, the content attribute always has a string value. For instance, you must use setAttribute("maxlength", "42") on an input element to set its max length to 42 using the content attribute.

The IDL (Interface Definition Language) attribute is also a JavaScript property. These attributes can be read or changed using JavaScript properties like element.foo. The IDL attribute will always use the underlying content property to return a value when you obtain it and will always be saved in the content attribute when you set it. In essence, the IDL properties represent the content attributes, in other words.

Not all IDL attributes are strings; for example, input.maxlength is a number (a signed long). When you use an IDL attribute, you read or set values of the desired type, so input.maxlength will always return a number when you set input.maxlength, it wants a number. According to the standard JavaScript type conversion rules, passing another type is immediately converted to a number.

IDL attributes can reflect on other types, such as unsigned long URLs, booleans, etc. Unfortunately, there are no hard-and-fast guidelines, and each IDL attribute's behaviour concerning its associated content attribute will vary. It will generally adhere to the specifications' guidelines, but occasionally it won't. The HTML specifications try to make this as developer-friendly as possible.

Some content attributes (for example, required, read-only, and disabled) are referred to as boolean attributes. If there is a boolean attribute, its value is true; otherwise, it is false.

HTML specifies the permitted values for boolean attributes: If the attribute exists, its value must be either the empty string (the attribute may have an unassigned value) or an ASCII case-insensitive match for the canonical name of the attribute, with no leading or trailing whitespace. Below are good ways to mark up a boolean attribute:

<div itemscope>This is valid HTML but invalid XML.</div>
<div itemscope="itemscope">This is also valid HTML but invalid XML.</div>
<div itemscope="">This is valid HTML and also valid XML.</div>
<div itemscope="itemscope">
This is also valid HTML and XML, albeit a little verbose.
</div>

The values "true" and "false" might not be allowed for boolean attributes. To represent a false value, the attribute must be removed entirely. This restriction clarifies a few common misconceptions: For example, with checked = "false," the element's checked attribute would be interpreted as true because the attribute is present.

I hope this article has given you a better understanding of HTML attributes and how to use them.