How do you comment your makefiles?

[Bahman Movaqar]

Hey all,

Fed up w/ my ad-hoc scripts to display the targets and variables in a
makefile(s), I've decided [1] to write a reusable piece of code to do
that: https://github.com/bahmanm/bmakelib/issues/81

The first step toward that would be to understand the common commenting
styles.  So far I have identified 4 patterns in the wild which you can
find below.

Are there any style guides/conventions around this topic?  Any references
to well-written makefiles I can get inspiration from?


――――――――――――――――――――  A  ―――――――――――――――――――――――――

VAR1 = foo   ## short one-liner comment
my-target: ## short one-liner comment 
        …


――――――――――――――――――――  B  ―――――――――――――――――――――――――

# longer comment which 
# may span
# several lines
VAR1 = foo

## comments can be prefixed w/ more than # 
## lorem ipsum dolor
my-target: 
        …


――――――――――――――――――――  C  ―――――――――――――――――――――――――

#####
# a comment block which is marked w/ several #s on
# an otherwise blank line
#####
VAR1 = foo


――――――――――――――――――――  D  ―――――――――――――――――――――――――

#####
#>    # heading 1
#     This is a variation to have markdown comments
#     inside makefile comments.
#
#     ## It's a made-up style!  
#     I came up w/ this style and used it to document `bmakelib`.
#     For example: https://is.gd/QtiqyA (opens github)
#<
#####
VAR1 = foo


-- 
Bahman

Join the chatter on Matrix:
         🗣️ https://matrix.to/#/#.mk:matrix.org
      
Subscribe to the Lemmy community:
         🐭 https://lemmy.ml/c/makefile