5

I occasionally come across questions that refer to several different source code files. In some questions, it's pretty clear which code belongs to which file, but not always. I often want to edit these questions to make the file association clearer and to make the question more readable, but there doesn't seem to be an obviously right way to format these.

Is there a good convention for representing this type of thing with SO markdown? Here are some of the examples I've seen for reference.

EDIT: I'm specifically referring to filename headers to code blocks, not formatting filenames in paragraph blocks (I think using inline-code or italics works well for that).

test.py (lead-in paragraph)

def blah():
    some code

test.py (bolded)

def blah():
    some code  

test.py (H3)

def blah():
    some code

test.py (horizontal rule)


def blah():
    some code
9
  • I personally use italics while mentioning the file name. Feb 1, 2016 at 20:39
  • 1
    Your question reads as if you are seeking the way to do it. I think there are multiple different ways to clearly delimit what belongs to one file. They are all fine. Also, just in case it needs to be mentioned, editing questions that are flat out unclear is fine. Editing questions that are clear but do not conform to someone's preferred style is not okay.
    – Louis
    Feb 1, 2016 at 20:41
  • 4
    Related on Meta.SE: Which markdown should be used for filename of code?
    – jscs
    Feb 1, 2016 at 20:43
  • @Louis Yeah, the ones I want to edit usually just contain the filenames in the paragraph preceding the code blocks, where it's not always clear which code block goes to which file at first glance. Feb 1, 2016 at 20:44
  • 1
    Are there languages where the file the code is in matters? As, in, you wouldn't be able to create an SSCCE that reproduces the issue? If not, then don't waste time telling me what file something is in. Represent the issue in the minimal amount of room required.
    – user1228
    Feb 1, 2016 at 21:59
  • @honk that question deals more with formatting filenames in paragraph blocks. This is more about filenames as code block headers. Feb 1, 2016 at 22:00
  • @BrendanAbel: I wouldn't go for a different formatting of a file name depending on where it is located in a post. I would vote for keeping the markup of file names consistently. However, if you have several very long code sections, then there might be exceptions to the rule...
    – honk
    Feb 2, 2016 at 7:43
  • 2
    I don't think this is a duplicate question. This question specifically deals with "there's a couple of blocks of code in this question; how can I make completely clear and unambiguous the file name of each block of code?" which only happens once per block. The "How should files names be formatted?" seems to be about mentioning the name of a file, even when that name is mentioned several times in a paragraph of text and the question may not even contain the contents of the file.
    – David Cary
    Feb 4, 2016 at 2:32
  • 1
    @Will: I agree that if a SSCCE can reproduce the issue with any file name, then a question doesn't need to mention a file name. However, many questions deal with the interactions between several files -- often a C or C++ header file and a couple of implementation files that #include that header file. I don't see how it's possible to create a SSCCE without mentioning the name of the header file.
    – David Cary
    Feb 4, 2016 at 2:42

0

Browse other questions tagged .