100

Many posts contain files' names and also the code contained in them. Usually I have found the file names formatted as code (my_file.py), in bold (my_file.py) or without format at all.

What's the formal way to format the file names?

9
  • 13
    I prefer italics for filenames. Commented Aug 22, 2015 at 11:35
  • 6
    Duplicate on Meta.SE: Which markdown should be used for filename of code
    – jscs
    Commented Aug 22, 2015 at 18:04
  • 32
    Please, don't use bold. It draws too much attention when the file name usually is not that important. Use bold for important things instead. Commented Aug 23, 2015 at 19:39
  • 4
    Just be happy it's included... :) I don't care how it's formatted, I'm way more concerned with whether I can understand the question and if the asker has put any effort into solving their own problem. IMO: it's not code so don't format it that way... it's not that important so don't bold it (plus it's distracting) and italics is for emphasis. I prefer to see it just as plain text. It should be clear to those involved that it's a file name all by itself.
    – JeffC
    Commented Aug 24, 2015 at 18:53
  • 1
    File names can be long and contain dots that might be confused with punctuation, and spaces, as sometimes happens in MS Windows. (Whole file paths can even contain slashes and colons.) Inline code style can prevent the such file names from blending in with surrounding sentence and thereby ruining it. For example: This is a sentence containing a file named oh this name has spaces.and.dots which may be hard to read without the file in inline code style. Italics or bold don't solve the problem well since they don't "bind" the parts of the file name as closely as the code style box. Commented Dec 10, 2018 at 9:54
  • It would be nice to find a thorough discussion of this in the context of Markdown in general rather than simply for Stack Overflow.
    – David J.
    Commented Oct 7, 2021 at 10:22
  • @JeffC it's not always clear that's a file name because it may contain spaces, dots and other words/punctuations. With a clear format it'll be much more readable
    – phuclv
    Commented Dec 15, 2021 at 10:13
  • @phuclv for files with spacing double quoting is appropriate - just as one would do in a terminal. No need for extra emphasis
    – 0Valt
    Commented Dec 15, 2021 at 12:28
  • 1
    @phuclv You are responding to a comment from 7 years ago... that said, if the filename contains spaces, etc. that you think might confuse a reader, you can easily enclose the entire file name in double quotes... it's still clear with no extra (incorrect) formatting needed.
    – JeffC
    Commented Dec 15, 2021 at 17:15

6 Answers 6

47

There is no formal answer in the formatting section of help for this. Thus at least I feel that the correct way to do it isn't about the format used but rather about consistence within the post. Also another point to be taken into consideration is the readability that can be improved greatly by differing between code blocks and file names if both are regularly used in the code.

6
  • 2
    +1 for mentioning the post's context. Still, personally I would not use italics for technical-relevant parts of my postings. I tend to use italics to indicate non-formal or sloppy parts, especially because I'm no native speaker.
    – Mischback
    Commented Aug 22, 2015 at 14:29
  • What about writing them in bold? is that also OK?
    – jchanger
    Commented Aug 22, 2015 at 15:01
  • 27
    @jessag: I personally wouldn't do that since bold is sign of importance or emphasis and thus has different purpose. Commented Aug 22, 2015 at 15:02
  • 2
    I can't accept "consistence within the post" as a valid answer. Of course that's important, but it could still look hideous, and what about consistence across the site? For me, it would make more sense if people posted all the reasonable options as answers to be voted on, and the top 1 or 2 voted answers becomes the standard. Commented Aug 24, 2015 at 16:34
  • 1
    I prefer code spans since actually, this is not italics but emphasized text (check the HTML source).
    – mb21
    Commented Aug 24, 2015 at 16:36
  • @Dukeling: I feel that no standard should be given for this because the use cases vary so heavily. For example, lets assume the inline code formatting was the standard for file names. Now, I am writing a lot of inline code blocks withing my post and need to include one file name in between of them. It wouldn't stand out at all and would mix to the code blocks. Lets take another example where the standard forces italics to be used instead. This time I'm writing a lot of library/programming language/product names in my answer and want to emphasis them with the italics. Same problem occurs. Commented Aug 24, 2015 at 18:56
17

At first sight, using code format is appealing. A file name may be thought of as being somewhat similar to code. As @LightnessRacesinOrbit so appropriately puts it in a comment, a file is a "thing that is quoted verbatim from a computer terminal", and thus it (more or less) qualifies as code. Still, in certain cases it may be desirable to have a format to distinguish file names from (the rest of the) code.

Another possibility is to use italic or bold. That way the file name is distinguished from actual code. But italic or bold are often used for emphasis. It would be best not to confuse a file name with an emphasized word or phrase.

Taking this into account, a good solution may be to use italic code or bold code format for file names. That way the filename looks similar to code, but there's a distinction. (And of course it should be used consistently thoughout the post, as mentioned by sanfor.)

6
  • 5
    The fact that a filename is not a function or a variable is a non sequitur. Things which are not functions or variables can appropriately have code formatting.
    – jwg
    Commented Aug 24, 2015 at 14:32
  • @jwg You are right. What I meant is that a filename is not exactly code. I've edited my answer.
    – Luis Mendo
    Commented Aug 24, 2015 at 15:12
  • 7
    @LuisMendo: No but it does fit the bill as a "thing that is quoted verbatim from a computer terminal" which I count as valid for code formatting. e.g. shell prompt, compilation command, output of -v, etc. Commented Aug 24, 2015 at 16:27
  • @LightnessRacesinOrbit Thanks. That's the idea I was struggling to convey when I said "being somewhat similar to code, like a variable or function name". I've edited my answer to incorporate this
    – Luis Mendo
    Commented Aug 24, 2015 at 17:52
  • 3
    Italic is all you need. The rest is too shouty, especially the fugly monospace.
    – tchrist
    Commented Aug 25, 2015 at 13:00
  • 1
    @tchrist But italic is also used for other purposes too, so it may be confusing. Besides, monospace is often associated with "things that are quoted verbatim from a computer terminal", such as a file. Is it "fugly"? That depends on personal taste :-)
    – Luis Mendo
    Commented Aug 25, 2015 at 16:49
14

Sometimes file names are specific commands to be run, and in that instance I think code formatting is most appropriate: netsh.exe show mode.

1
  • 3
    +1: If it is a fixed name that the user should type exactly as shown, use code formatting. If it is a placeholder or example file name that the user can or should replace then italic is more appropriate.
    – mark4o
    Commented Aug 24, 2015 at 19:11
3

There are different options:

  • plugin.yml
  • plugin.yml
  • plugin.yml
  • plugin.yml
  • plugin.yml
  • plugin.yml
  • plugin.yml
  • plugin.yml
  • plugin.yml
  • plugin.yml
  • plugin.yml
  • plugin.yml

Personally, I use italic formatting.

  • plugin.yml
6
  • If you want to enumerate them... Abuse of intended usage: <kbd>plugin.yml</kbd> (which is fully nestable with all the others. I actually rather like how <kbd>*plugin.yml*</kbd> looks, now that I've seen it)
    – Izkata
    Commented Aug 25, 2015 at 4:59
  • @Izkata Added more options.
    – user3453226
    Commented Aug 25, 2015 at 12:05
  • 6
    Anything but the first two sucks, because the rest of them mangle the page color. They should be reserved for ransom notes.
    – tchrist
    Commented Aug 25, 2015 at 12:57
  • using <kbd> tag in markup is not appropriate for a filename, in general. "The <kbd> HTML element represents a span of inline text denoting textual user input from a keyboard, voice input, or any other text entry device." per developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd
    – David J.
    Commented Oct 7, 2021 at 10:10
  • For one specific use, it might be semantically ok to use the <kbd> tag: when the document is directing a user to type a filename. Generally speaking, this is not how filenames are used in documentation.
    – David J.
    Commented Oct 7, 2021 at 10:12
  • @tchrist I personally appreciate the humor; however, your rationale above uses appearance (e.g. page color, a 'presentation' issue) as a justification. It is better to choose markup based on semantics. One reference: marcomm.nd.edu/blog/always-use-semantic-markup
    – David J.
    Commented Oct 7, 2021 at 10:17
2

At least with code, we use file names—verbally and in writing—almost like the title of the contents within the files.

For a creative work, such as a novel or a film, we italicize the title of the work. Although I'll never write a piece of code as magnificent as The Lord of the Rings, I don't think it's too much of a stretch to consider code as a type of composition and to suggest that we use italics when citing the "titles":

  • "The server seems stuck in an infinite loop at RingCollectionSingleton.java, line 1."
  • "How can I decouple my code from DisposableOrcFactory.cs?"
  • "Whoops! I forgot to check in changes to DarkLord.php yesterday..."
  • "I need help debugging my wizardry.sh. It's keeping our tests from passing."

As illustrated above, italics provide a reasonable distinction for file names, at least visually. For those of us resolutely concerned about the semantics of markup generated, we can use <i>…</i> tags in place of markdown to avoid designating titles as emphasis.

Speaking of semantics, inline code formatting seems like fair option, but I think we can distinguish between referring to a file ("here's my .htaccess") and describing a file name used in code or a command ("check that somefile.csv exists in that function") by marking the former with italics and the latter as code.

-5

In my opinion, all code related things should be used in code blocks, thus being more pleasant for the viewer. But it doesn't have a formal way to do that.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .