4

Every now and then I run into questions, initially containing a descriptive block of text that explains the background and experienced problem, followed by a code snippet and eventually a stack-trace if there's a crash.

Usually, these initial descriptive block of texts contains some references to the up-coming code snippets.

For example:

"I'm experiencing a unexpected behavior when calling anObscureMethod() in MyJavaClass.java. I suspect it's due to thisOddVariable, but it might also be..."

Followed by

private class MyJavaClass{
    public void anObscureMethod(){
        ...
    }
}

Up until now, I've been suggesting edits to format the initial descriptive text as below.

"I'm experiencing a unexpected behavior when calling anObscureMethod() in MyJavaClass.java. I suspect it's due to thisOddVariable, but it might also be..."

This is in my opinion more readable because it separates the code and gives a better overview of the question as a whole.

The purpose of this question is that I've recently seen posts from more established users, where no such code formatting is present. So I'm simply wondering, is there a policy on this? Is it considered as an individual preference, meaning I should not be suggesting these kinds of edits?

1
  • 4
    I personally make these edits quite often, usually when the lack of formatting makes it very difficult to follow what they are saying (like when variables are common words, short letters, etc). These edits should be fine, as long as you fix all of the issues and not just the small formatting issues. Commented Feb 20, 2015 at 23:21

1 Answer 1

4

You're doing the right thing here; that's what inline code is for.

There are varying opinions on whether they should be used for file names, but if you're highlighting code, you're using the backticks properly.

It very much is individual preference, but that doesn't necessarily mean that you shouldn't be suggesting edits with it, because the opinion comes in when you're considering how much you are using the formatting. It can get a bit messy if you try to use it too much, but that's up to your (and your reviewers') discretion.

So, for example, in the case you describe above, I'd change it to this:

I'm experiencing a unexpected behavior when calling anObscureMethod() in MyJavaClass.java. I suspect it's due to thisOddVariable, but it might also be...

That's the best compromise you can usually come to (used strictly for code not in code blocks).

You must log in to answer this question.

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