Consensus on when markdown code formatting should be used

Question

I've noticed that there is some missuse of markdown code formatting here. Before I go around editing it out, it would be good to come to a consensus on when it is appropriate.

In my opinion, the following is true:

Appropriate

• Code blocks (obviously), e.g.

  def id_func(x):
      if x.featuretype == 'gene':
          new_id = x.attributes['ID'][0]
      elif x.featuretype == 'CDS':
          new_id = '-'.join( [x.attributes['ID'][0], x.seqid, str(x.start), str(x.end)] )
      return new_id
  

• Error messages and other formatted text output, e.g.

  print("1" + '"' + str(fastaIdx) + '"' + '"' + str(mrna_id) + "'" + db.strand())
  AttributeError: 'FeatureDB' object has no attribute 'strand'
  

• Formatted data, e.g.

  Seq_18  Liftoff gene    653259  653653  .       +       .       ID=QZVMAR_2781_gene_1
  Seq_18  Liftoff CDS     653259  653334  .       +       .       ID=Seq_8_Seq_8_Manual.BlastoST7C_030513:00:54_1;Parent=QZVMAR_2781_gene_1
  Seq_18  Liftoff CDS     653370  653458  .       +       .       ID=Seq_8_Seq_8_Manual.BlastoST7C_030513:00:54_1;Parent=QZVMAR_2781_gene_1
  Seq_18  Liftoff CDS     653489  653543  .       +       .       ID=Seq_8_Seq_8_Manual.BlastoST7C_030513:00:54_1;Parent=QZVMAR_2781_gene_1
  Seq_18  Liftoff CDS     653577  653653  .       +       .       ID=Seq_8_Seq_8_Manual.BlastoST7C_030513:00:54_1;Parent=QZVMAR_2781_gene_1
  

• Referring to inline function names, e.g.

  You should only use printf when....

Not appropriate

• When emphasising words in a sentence
• When referring to the name of a piece of software pandas or programming language python
• Anything else that isn't covered by the above points

Up for discussion

• When referring to filenames test.fastq

Does the comminity agree? Are there any additions or removals that people think are appropriate?

Answer 1

Summary A distinction between library and function/method appears to be at the heart of this proposal. I can't see this proposal working for inline text for OO code (such as Python) because it is not practical to separate the library from a method (equivalent of a function).

Background Specifically on a spectrum from Python to pandas and then to printf. pandas is a library imported into Python. It's popular possibly because it's faster (for Python). It uses a sort of type casting, which I assume speeds its interaction with the underlying C.

Issues for inline text

1. For inline text what's the difference between printf (which is very C, but also Perl) and pandas, neither are standalone languages? If there is a distinction, where is the line drawn, for example what about math.h (C), numpy or for example pathlib which are all 'libraries'? If libraries are excluded (of which pandas is one) what about the methods (OOP) that they are importing? For example, would Path in pathlib library be okay (thats a method), but the pathlib library itself be excluded from the proposal?
2. Is there a distinction between functions and methods, i.e. between a non-OOP language and an OOP? I assume f strings or format (Python's equivalent to printf) are fine, but these are methods rather than functions. If methods were excluded it would be a bit limiting to an OOP coder.
3. Furthermore, OOP uses libraries and method calls in the unit of code, i.e. " library.method ". For example, the pandas library calls methods within the code not on import, so in the code below (df = pd.DataFrame()) would literally read pd.DataFrame as inline text. This is because DataFrame is the method and pd is the abbreviation for the library its from, i.e. pandas. The proposal appears to permit the method to be greyed out in inline text but the library isn't.

---

I assume that the proposal for pandas i.e.

import pandas as pd
df = pd.DataFrame()

Would not extend to

import pandas as pd

df = pd.DataFrame()

I hope thats right?