MarkdownToHtmlTranspiler/doc/StyleGuide.md

MarkdownToHtmlTranspiler – Style Guide

Purpose:
This guide defines the coding, formatting, and contribution standards for all contributors to the MarkdownToHtmlTranspiler project. It ensures that all code remains consistent, maintainable, while supporting clarity.

---

Project Overview

This project is a C++ Markdown to HTML transpiler, converting Markdown files into HTML using a structured parsing system.
The repo includes:

• Build tooling: Makefile, flake.nix, and related Nix configurations
• Libraries & sources: Under src/ and lib/
• Docs & UML: Project diagrams and notes describing architecture

---

⚙️ 1. Repository Layout

Path	Purpose
src/	Main function
lib/	Helper modules or shared logic reused across the project
test/	HTML output files
Makefile	Primary build automation script
flake.nix / flake.lock	Nix build and dependency management files

File Naming

• Source files: camelCase.cpp

---

💻 2. C++ Code Style

General Formatting

• Indentation: 2 spaces (no tabs)

• Line length: 150 characters max

• Braces:

  if (condition) {
    doSomething();
  } else {
    doSomethingElse();
  }
  
  

• Spacing:

  • Put a single space after commas and around binary operators.
  • No spaces after ( or before ).
  • Example:

    result = func(x, y + 1);
    

Naming Conventions

• Classes & Structs: PascalCase
  Example: Parser, DomTree
• Functions & Methods: PascalCase
  Example: Inspect(), ParserDocument()
• Variables & Parameters: snake_case
  Example: input_file, output_path
• Constants: ALL_CAPS_WITH_UNDERSCORES
  Example: MAX_BUFFER_SIZE
• Namespaces: lowercase

---

Error Handling

Use exceptions for runtime errors (std::runtime_error, std::invalid_argument, etc.).

Always catch by reference.

Example:

try {
  Parser p(argv[1]);
  p.Inspect();
} catch (const std::runtime_error &e) {
  std::cerr << "Error: " << e.what() << std::endl;
}

3. Commenting & Documentation Style

General Rules

• Use // for short inline comments.
• Use /** ... */ for function, class, or member documentation.
• Start each docblock with @brief for a concise description.
• Include @param, @return, and @throws (if applicable).
• Always describe the intent, not just what the code does.
• Add @author for major contributors.

• 🔹 Example: Class Documentation

Below is a properly documented example class showing how to format comments consistently throughout your codebase:

/**
* @file commandLineParser.h
* @brief Parses command line
* @author Preston Shultz
* Sources:
*
*/

#ifndef COMMAND_LINE_PARSER_H
#define COMMAND_LINE_PARSER_H
  
#include  <string>
#include  <vector>
  
/**

* @brief CommandLine Helper class
*
* Parse input arguments, sets input and output files
* Lets user use commands with program
*
* @author Preston Shultz (shultzp1@my.erau.edu)
*/
class  CLI {

public:
/**
* @brief Takes in argc and argv and converts it to vector
*
* CLI constructor
*
* @author Preston Shultz (shultzp1@my.erau.edu)
*/
CLI(int  argc, char  **argv);


/**
* @brief Runs Commands
*
* @author Preston Shultz (shultzp1@my.erau.edu)
*/
void  RunCommands();


/**
* @brief Prints a list of commands that can be used
*
* @author Preston Shultz (shultzp1@my.erau.edu)
*/
void  PrintHelp() const;


/**
* @brief Returns input file
*
* @author Preston Shultz (shultzp1@my.erau.edu)
*/
std::string  GetInputFile() const { return input_file; }


/**
* @brief Returns if watchdog is enabled
*
* @author Preston Shultz (shultzp1@my.erau.edu)
*/
bool  WatchDogEnabled() {return watchdog_enabled;}


/**
* @brief Returns output file
*
* @author Preston Shultz (shultzp1@my.erau.edu)
*/
std::string  GetOutputFile() const { return output_file; }


private:
/**
* @brief Ensures the provided filename has a .markup extension
*
* @return true if file ends with .markup
* @return false otherwise
* @author Preston Shultz (shultzp1@my.erau.edu)
*/
static  bool  IsMarkupFile(const  std::string  &filename);


/**
* @brief Ensures the provided filename has a .html extension
*
* @return true if file ends with .html
* @return false otherwise
* @author Preston Shultz (shultzp1@my.erau.edu)
*/
static  bool  IsHtmlFile(const  std::string  &filename);
  

/**
* @brief Parses the commands
*
* @author Preston Shultz (shultzp1@my.erau.edu)
*/
void  ParseArgs(int  argc, char**  argv);
  

std::string program_name;
std::string input_file;
std::string output_file =  "";
bool watchdog_enabled =  false;
};

#endif