Comments (-- and {- -})

-- Single-line comment. Everything from -- to the end of the line is a comment.

x = 10  -- Inline comment. Use this to add a short note to the right of code.

{-
  Block comment.
  Everything between {- and -} is a comment.
  Nesting is supported: {- outer {- inner -} outer continued -}
-}

-- | Haddock documentation comment (written before the definition).
-- Describes the function add.
add :: Int -> Int -> Int
add x y = x + y

-- ^ Haddock documentation comment (written after the definition).

{-| Block-form Haddock comment.
    Use this when you want to write a multi-line description.
-}

Type	Syntax	Description
Single-line comment	-- text	Everything from -- to the end of the line becomes a comment. Can be placed at the start of a line or after code on the same line.
Block comment	{- text -}	A multi-line comment. Nesting is allowed: block comments can be nested inside other block comments.
Haddock (leading)	-- | text	A Haddock documentation comment written immediately before a function, type, or data constructor.
Haddock (trailing)	-- ^ text	A Haddock documentation comment written immediately after a definition. Used to describe record fields and function arguments.
Haddock (block leading)	{-| text -}	A block-form Haddock leading comment. Use this when writing a long description over multiple lines.

Haddock is a tool that automatically generates API documentation for Haskell. When a package is uploaded to Hackage, HTML documentation is generated from the Haddock comments. Locally, documentation can be generated with cabal haddock or stack haddock.

-- | is a documentation comment for the definition that follows it. -- ^ is a documentation comment for the definition immediately preceding it. The block forms {-| -} and {-^ -} can also be used in the same way.

Notation	Usage
-- | text	Documents the next definition (function, type, data constructor, etc.).
-- ^ text	Documents the immediately preceding definition. Used to annotate record fields, type parameters, and function arguments.
{-| text -}	Block-form leading documentation comment.
{-^ text -}	Block-form trailing documentation comment.
@param name description	Documents a parameter (Haddock notation).
== section name	Creates a section heading inside the documentation.
$sectionname	Inserts a section reference in the module-level documentation.

Decision	Situation	Reason
Write a comment	The reason why something was implemented a certain way	Design decisions and trade-offs that cannot be understood from the code alone help your future self and other developers.
Write a comment	Functions whose intent cannot be conveyed by the type signature alone	Haskell has an expressive type system, but types alone cannot always communicate preconditions, side effects, or performance characteristics.
Write a comment	Public library functions, types, and data constructors	Writing Haddock comments enriches the documentation page on Hackage, making it easier for users to consume the library.
Write a comment	Temporarily disabled code during debugging	Leaving a note explaining why code was commented out and when it can be removed reduces the risk of forgetting to clean it up later.
No comment needed	Logic that is obvious from reading the code	Self-evident comments become noise. Clear function names and type signatures can eliminate the need for such comments.
No comment needed	Change history or deleted code	Because version control (git) is available, there is no need to keep old code or change dates in comments.

Basic usage of single-line and block comments.

comment_basic.hs

-- A sample that computes basic statistics for score data.

module Main where

import Data.List (sort)

-- List of scores.
scores :: [Double]
scores = [85, 92, 78, 95, 61]

{-
  Basic statistics calculations.
  average: returns the mean of a list.
  median : returns the median of a list (assumes sorted input).
-}

-- | Computes the average of a list of numbers.
average :: [Double] -> Double
average xs = sum xs / fromIntegral (length xs)

-- | Computes the median of a sorted list.
median :: [Double] -> Double
median xs =
    let sorted = sort xs
        n = length sorted
    in if odd n
       then sorted !! (n `div` 2)
       else (sorted !! (n `div` 2 - 1) + sorted !! (n `div` 2)) / 2

main :: IO ()
main = do
    let avg = average scores  -- compute the average
    let med = median scores   -- compute the median
    putStrLn $ "Count : " ++ show (length scores)
    putStrLn $ "Average: " ++ show avg
    putStrLn $ "Median : " ++ show med

The same logic can also be written as:

$ runhaskell comment_basic.hs
Count : 5
Average: 82.2
Median : 85.0

Attaching Haddock documentation comments to functions and types.

calculator.hs

{-|
Module : Calculator
Description : A module providing basic arithmetic operations.
-}
module Calculator
    ( add
    , subtract'
    , divide
    ) where

-- | Adds two numbers.
--
-- >>> add 3 4
-- 7
add :: Int -> Int -> Int
add x y = x + y

-- | Subtracts the second number from the first.
subtract' :: Int -> Int -> Int
subtract' x y = x - y

{-| Performs division.
    Returns Nothing if the divisor is zero.
-}
divide :: Double -> Double -> Maybe Double
divide _ 0 = Nothing  -- ^ Returns Nothing on division by zero.
divide x y = Just (x / y)

The same logic can also be written as:

$ ghci calculator.hs
ghci> add 10 5
15
ghci> subtract' 10 3
7
ghci> divide 10 3
Just 3.3333333333333335
ghci> divide 10 0
Nothing

Haskell comments come in two types: single-line comments (--) and block comments ({- -}). Block comments support nesting, which means a block comment can appear inside another block comment. This is handy when temporarily disabling a section of code that already contains a block comment.

Use Haddock notation for API documentation. Pay attention to the difference between -- | (leading) and -- ^ (trailing). Use -- | when writing a comment before a function or type definition; use -- ^ when adding a note after the immediately preceding definition or field. With Haddock comments in place, cabal haddock automatically generates HTML documentation, and the documentation page on Hackage is populated accordingly.

Mixing up -- | and -- ^

-- | documents the definition that follows it, while -- ^ annotates the definition immediately before it. Using them in the wrong place associates the documentation with an unintended definition.

Forgetting the closing -} of a block comment

If you write {- but forget the closing -}, all subsequent code is treated as a comment. Use your text editor's syntax highlighting to verify that the comment boundaries are correct.