General

All files include some level of explanation so that you can quickly understand what the file is supposed to be doing, what it depends on, and how it works.

Some files have a dedicated explanation of the purpose at the top of the page, like:

// Purpose: The purpose of this file is ...

All component files have JSDoc like comments to quickly understand what is going on, like:

/**
 * Renders a section breaker component, with a title and a description.
 *
 * @param title - The title of the section breaker.
 * @param description - The description of the section breaker.
 * @param className - The additional CSS class name for the section breaker.
 * @returns The rendered section breaker component.
 */
export default function BreakerSection({}){return()}

All files follow the same structure at the top:

// Import Types <- TypeScript Types
// Import External Packages <- External Packages like React
// Import Components <- Your own Ui & functional components
// Import Functions & Actions & Hooks & State <- Your own functions, server actions, hooks and state functions
// Import Data  <- Constants or other data
// Import Assets & Icons <- Icons and other static assets
// Import Error Handling <- Server Actions also include dedicated Error Handling Functions

The structure allows to quickly get an overview of what is flowing into the file at hand.

To give an example, here is a Back To Top Button. Every other component will have the same level of documentation.

'use client';

// Import Types
// Import External Packages
// Import Components
import { Button, ButtonProps } from '@/ui/Button';
// Import Functions & Actions & Hooks & State
import { cn } from '@/lib/utils';
// Import Data
// Import Assets & Icons
import { ArrowUp } from 'lucide-react';

/**
 * Renders a button component that scrolls the page to the top when clicked.
 *
 * @param buttonText - The text to display on the button. Default is 'Back to top'.
 * @param showArrowIcon - Determines whether to show an arrow icon next to the button text. Default is true.
 * @param className - Additional CSS class names to apply to the button.
 * @param variant - The variant of the button. Default is 'secondary'.
 */
export default function Button_BackToTop({
	buttonText = 'Back to top',
	showArrowIcon = true,
	className,
	variant,
}: {
	buttonText?: string;
	showArrowIcon?: boolean;
	className?: string;
	variant?: ButtonProps['variant'];
}) {
	// Function to scroll the page to the top when the button is clicked
	const handleClick = () => {
		window.scrollTo({ top: 0, behavior: 'smooth' });
	};

	return (
		<Button
			className={cn('fixed bottom-4 right-4 z-50', className)}
			onClick={handleClick}
			variant={variant || 'secondary'}
		>
			{buttonText}
			{showArrowIcon && <ArrowUp size={18} className="pl-1" />}
		</Button>
	);
}