Python: What is a header?

Question

I\'m new to Python and programming in general. I am taking a module at university which requires me to write some fairly basic programs in Python. However, I got this feedback o

Answer 1

My Opinion

I use this this format, as I am learning, "This is more for my own sanity, than a necessity."

As I like consistency. So, I start my files like so.

#!/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 is the Shebang
   1. And I know There's no reason for most Python files to have a shebang line but, for me I feel it lets the user know that I wrote this explicitly for python3. As on my mac I have both python2 & python3.
2. Line 2 is the encoding, again just for clarification
   1. As some of us forget when we are dealing with multiple sources (API's, Databases, Emails etc.)
3. Line 3 is more of my own visual representation of the max 80 char.
   1. I know "Oh, gawd why?!?" again this allows me to keep my code within 80 chars for visual representation & readability.
4. Line 4 & 5 is just my own way of keeping track as when working in a big group keeping who wrote it on hand is helpful and saves a bit of time looking thru your GitHub. Not relevant again just things I picked up for my sanity.
5. Line 7 is your Docstring that is required at the top of each python file per Flake8.

Again, this is just my preference. In a working environment you have to win everyone over to change the defacto behaviour. I could go on and on about this but we all know about it, at least in the workplace.

Header Block

• What is a header block?
• Is it just comments at the top of your code or is it be something which prints when the program runs?
• Or something else?

So in this context of a university setting:

Header block or comments

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

• Is it just comments at the top of your code or is it be something which prints when the program runs? Or something else?

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

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

ie:

# 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 the python way using "Module Level Dunder Names"

Standard Module Level Dunder Names

__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__ = 'Jahomie04@gmail.com'
__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 would like.

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)

End RESULT

Every time the program gets called it will show the 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: Jahomie04@gmail.com
Status: Prototype
Course: CS108
Laboratory: A13
Date: 2018/08/18
Username: JayRizzo
Description: My First Project Program.
# ==============================================================================

Notes: If you expand your program just set this once in the init.py and you should be all set, but again check with the professor.

If would like the script checkout my github.

Answer 2

A header block are just comments at the top of the code. It doesn't print when the program runs.

A example could look like the following:

# 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 3

Very good discussion here --> What is the common header format of Python files?

The Python docstring should be concise, and not really contain revision history, or anything not directly related to the current version behaviour. I have yet to see "man" style docstrings and it may be just as well.

A flower box, with revision history independent of source control (as some of the revisions may pre-date your source control eventually) goes back to the days of reading code on paper or as emailed. We were not always as connected as we are now.

Using a modern IDE this has fallen out of favour, but can be seen for older/larger high level works. In some shops the sign in is not performed by the coder, especially if the code has been "shopped out". Some signin's are commented in a lazy, slovenly fashion.

So it varies, but :

#! /usr/bin/python
#--------------------------------#
# optional flower box  
#--------------------------------#
""" 
Multiple lines of doc if required
"""

import foo
import bar

__metastuff__ = 'some value'

I see the 'meta' higher up, notably in the youtube promotionals for "pycharm". People like to see it below the imports as it is really code and the imports are expected to come before the code. I can imagine it may become easy to get carried away. Sensible and informative comments in the low level code are worth way more than what is written upstairs anyway.

In the real world, just do what everybody else is doing on your project and you will be fine. It is common to re-use a template anyway, or copy and paste (i.e. ripoff) from a "prototype".

Answer 4

In this context, you are correct. A header block means a set of comments at the top of the source file that contains the requested information. It does not need to contain any code that does anything.

Answer 5

Your instructor wants you to add some information to your assignment's source code's top section something like this, so you are right you will add comments:

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

Answer 6

There's thing called Docstring in python (and here're some conventions on how to write python code in general - PEP 8) escaped by either triple single quote ''' or triple double quote """ well suited for multiline comments:

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

You also may used special variables later (when programming a module) that are dedicated to contain info as:

__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__ = "rob@spot.colorado.edu"
__status__ = "Production"

More details in answer here.