Python: What is a header?

Question

I am new to Python and programming in general. I take a module at the university that requires me to write some fairly simple Python programs. However, I received this feedback for my last assignment:

There should be a header block containing the file name, author name, created date, date and python version

What is a title block? Are these just comments at the top of your code, or is it something that prints when the program starts? Or something else?

Answer 1

It calls Docstring in python (and here are some conventions on how to write Python code in general - PEP 8 ), escaped with a triple single quote ''' or a triple double quote """ , well suited for multi-line comments:

 ''' File name: test.py Author: Peter Test Date created: 4/20/2013 Date last modified: 4/25/2013 Python Version: 2.7 ''' 

You can also use special variables later (when programming the module), which are designed to place information like:

 __author__ = "Rob Knight, Gavin Huttley, and Peter Maxwell" __copyright__ = "Copyright 2007, The Cogent Project" __credits__ = ["Rob Knight", "Peter Maxwell", "Gavin Huttley", "Matthew Wakefield"] __license__ = "GPL" __version__ = "1.0.1" __maintainer__ = "Rob Knight" __email__ = " [e-mail] " __status__ = "Production" 

Read more in the answer here .

Answer 2

Your instructor wants you to add some information to the top section of the destination source code, something like this, so you're right, you will add comments:

 #################################### # File name: ... # # Author: ... # # Submission: # # Instructor: # #################################### 

Answer 3

The title block is just the comments at the top of the code. It does not print when the program starts.

An example might look like this:

 # File name: test.py # Author: Peter Test # Date created: 4/20/2013 # Date last modified: 4/25/2013 # Python Version: 2.7 # Begin code a = 1 b = 2 c = a + b print c 

Answer 4

Very good discussion here -> What is the general format of the Python file header?

The Python documentation line should be concise and not contain a change history or anything that is not directly related to the behavior of the current version. I haven’t seen a string of masculine-style documents yet, and it can be just as good.

A flower box with revision history that is independent of version control (as some of the revisions may eventually precede your version control system) goes back to days of reading code on paper or by email. We were not always as connected as we are now.

Using a modern IDE, this got out of hand, but it can be seen for older / larger high-level jobs. In some stores, login is not performed by the encoder, especially if the code has been "bought out". Some sign comments in a lazy, untidy way.

So that is changing, but:

 #! /usr/bin/python #--------------------------------# # optional flower box #--------------------------------# """ Multiple lines of doc if required """ import foo import bar __metastuff__ = 'some value' 

I see the “ meta ” above, especially in YouTube promotions for “pycharm”. People like to see this under import, as this is really a code, and it is expected that the import will precede the code. I can imagine that it can become easy to get carried away. Reasonable and informative comments in low-level code in any case cost much more than what is written above.

In the real world, just do what everyone else in your project does, and you will be fine. In any case, usually reusing a template or copying and pasting (ie ripoff) from a “prototype”.

Answer 5

My opinion

I use this format in the learning process: "This is more for my common sense than for necessity."

How I love the sequence. So, I start my files like this.

 #!/usr/bin/env python3 # -*- coding: utf-8 -*- # ============================================================================= # Created By : Jeromie Kirchoff # Created Date: Mon August 18 18:54:00 PDT 2018 # ============================================================================= """The Module Has Been Build for...""" # ============================================================================= # Imports # ============================================================================= from ... import ... <more code...> 

1. First line - Shebang
   1. And I know, There no reason for most Python files to have a shebang line but I feel like it lets the user know that I wrote this explicitly for python3. As on my Mac, I have both python2 and python3.
2. Line 2 is an encoding, again just for clarification
   1. How some of us forget when we deal with several sources (APIs, databases, emails, etc.)
3. Line 3 is my own visual representation of max. 80 characters.
   1. I know, "Oh god, why?!?" Again, this allows me to keep my code within 80 characters for visual presentation and readability.
4. Lines 4 and 5 are my own way of tracking, as working in a large group that writes this at hand is useful and saves a little time when viewing your GitHub . Again, it’s not relevant only what I picked up for sanity.
5. Line 7 is the documentation line that is required at the top of each Python file for each Flake8 .

Again, these are just my preferences. In a working environment you must engage everyone in order to change de facto behavior. I could go on and on about it, but we all know about it, at least in the workplace.

Title block

• What is a title block?
• Are these just comments at the top of your code, or is this what gets printed when the program starts?
• Or something different?

So, in this context, the university settings:

Title block or comments

Header comments appear at the top of the file. These lines usually include the file name, author, date, version number, and a description of what the file is intended for and what it contains. For class assignments, headings should also include things such as course name, number, section, instructor, and assignment number.

• Are these just comments at the top of your code, or is this what gets printed when the program starts? Or something different?

Well, it can be interpreted differently by your professor, demonstrate it and ask!

"If you never ask, the answer is ALWAYS No."

i.e:

 # Course: CS108 # Laboratory: A13 # Date: 2018/08/18 # Username: JayRizzo # Name: Jeromie Kirchoff # Description: My First Project Program. 

If you are looking for Overkill:

or python path using "module level dunder names"

Standard Dunder Names Level Modules

 __author__ = 'Jeromie Kirchoff' __copyright__ = 'Copyright 2018, Your Project' __credits__ = ['Jeromie Kirchoff', 'Victoria Mackie'] __license__ = 'MSU' # Makin' Shi* Up! __version__ = '1.0.1' __maintainer__ = 'Jeromie Kirchoff' __email__ = ' [e-mail] ' __status__ = 'Prototype' 

Add your own custom names:

 __course__ = 'cs108' __teammates__ = ['Jeromie Kirchoff'] __laboratory__ = 'A13' __date__ = '2018/08/18' __username__ = 'JayRizzo' __description__ = 'My First Project Program.' 

Then just add a little code to print if the instructor wants.

 print('# ' + '=' * 78) print('Author: ' + __author__) print('Teammates: ' + ', '.join(__teammates__)) print('Copyright: ' + __copyright__) print('Credits: ' + ', '.join(__credits__)) print('License: ' + __license__) print('Version: ' + __version__) print('Maintainer: ' + __maintainer__) print('Email: ' + __email__) print('Status: ' + __status__) print('Course: ' + __course__) print('Laboratory: ' + __laboratory__) print('Date: ' + __date__) print('Username: ' + __username__) print('Description: ' + __description__) print('# ' + '=' * 78) 

Final result

Each time the program is called, it will display a list.

 $ python3 custom_header.py # ============================================================================== Author: Jeromie Kirchoff Teammates: Jeromie Kirchoff Copyright: Copyright 2018, Your Project Credits: Jeromie Kirchoff, Victoria Mackie License: MSU Version: 1.0.1 Maintainer: Jeromie Kirchoff Email: [e-mail] Status: Prototype Course: CS108 Laboratory: A13 Date: 2018/08/18 Username: JayRizzo Description: My First Project Program. # ============================================================================== 

Notes: If you are expanding your program, just install it once in init .py and everything should be ready, but consult with the professor again.

If I would like a script to check my GitHub.

Answer 6

In this context, you are right. Title block means a set of comments at the top of the source file that contains the requested information. It should not contain any code that does anything.