Re: How do you comment your makefiles?

[Christian Hujer]

Hey Braham,

you might be interested in these:

   - makehelp, a Perl script that is a bit like a little Doxygen for your
   Makefiles. https://github.com/christianhujer/makehelp
   I created it 9 years ago.
   - Or just this:

.PHONY: clean
## clean: Removes all generated files.
clean::
        $(RM) *.[adios]

.PHONY: help
## help: Prints this help text.
help:
        sed -n 's/^## \?//p' $(MAKEFILE_LIST)

I first document for the user, want that `make help` tells users how to use
the Makefile. And that would typically be displayed on the command line,
when someone types `make help`.
I usually don't document my variables or targets from an implementation
perspective, I try to use good, that is, self-documenting,
intent-communicating symbol names.

Best regards,
Christian


On Sun, Oct 22, 2023 at 10:14 PM Bahman Movaqar <bahman@bahmanm.com> wrote:

> 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
>
>
>
>
>

-- 
Christian Hujer
CEO/CTO
Nelkinda Software Craft Pvt Ltd
📧 Christian Hujer <Christian.Hujer@nelkinda.com> | 𝕏 @nelkinda
<https://twitter.com/nelkinda> | 🌐 https://nelkinda.com
☏ 🇮🇳 ✆ +91 77 2003 6661 <+917720036661>