Code covered by the BSD License  

Highlights from
M-file Header Template

4.4

4.4 | 10 ratings Rate this file 78 Downloads (last 30 days) File Size: 2.22 KB File ID: #4908

M-file Header Template

by

 

12 May 2004 (Updated )

Promotes better m-file documentation by encouraging authors to produce informative headers.

| Watch this File

File Information
Description

To contribute to better standards of m-file documentation on the MATLAB Central File Exchange, I am proposing a template m-file header.

The template starts with the H1 line, followed by a few lines to describe what the function does in greater details, the calling syntax, a description of each input and output variable, a practical example of function usage, information concerning other m-files or mat-files that may be required for this function to run, and a "See also" line leading to closely related functions. This ends the block of header lines that are displayed in the command window by typing "help function_name".

After an empty uncommented line, a second block of commented lines presents information about the author: name, job title, email, website, dates of file creation and last file modification. Finally, there is a %---Begin code --- line and a % --- End code --- line.

I have surely overlooked to include information that other m-file authors consider essential. If you have suggestions to improve the template, I would appreciate hearing about them and I will try to include them in a future version. Please do not make a separate submission on the File Exchange for relatively minor modifications to this template. New submissions on the File Exchange that are based on existing submissions should only be considered when major changes in functionality are offered by the new submission (IMHO).

You should edit template_header.m and save a customized version of it containing your own personal info, as shown in template_dg.m. This will save you from typing repetitive author info each time you create a new m-file.

Acknowledgements

This file inspired Ocean Map, Newm, and Default Path Retrieval.

MATLAB release MATLAB 6.5 (R13)
Tags for This File   Please login to tag files.
Please login to add a comment or rating.
Comments and Ratings (13)
15 May 2013 Alexandre Willame

What everyone should use (even just partially) to quickly and nicely make their templates.

09 May 2013 gbernardi

Great job. It's always been confusing to decide what information to put and in which order in my files.
Now, you finally solved that problem :)

28 Jun 2011 Peter Bosler

This is great. My only suggestion would be to add a "TO DO : " block to help out next versions of the code.

27 Jan 2011 George

I too would like to know where to save the template file so that MATLAB opens it when I create new m files.
Is this possible?

31 Mar 2010 Airballman

Perfect. That is what is was searching for.

Thx, I ll be pleased to use your notations.

05 Feb 2009 Pabs

love the layout..
now where do you put the template so that Matlab opens it up every time I ask to create a NEW m file?

thanks

Pabs

03 Jul 2008 Tom Clark

I've now been using this daily for over a year. Fantastically good!

My advice is to fill it in rigorously every time you create an m-file. That way you build up an entire documentation system for your functions, without a dedicated and massive effort to document them all at once.

I disseminated this header format into my previous workplace... When I left, there was hardly any panic, as everyone could figure out what my codes did! Thanks Denis...

05 Jul 2007 Giovani Tonel

Excellent attempt Mr. Denis, I will use this format in my future works.

Regards!

Giovani Tonel

Post-Graduation (Taking Master Degree) in Chemical Engineering

Federal University of State of Rio Grande Sul - UFRGS

Porto Alegre, RS - Brazil

GIMSCOP/ALSOC - http://www.enq.ufrgs.br/gimscop

Chemical Engineering Department
Phone: +55 51 3308 4166 (GIMSCOP - Room 2)

06 Jun 2007 mahdi ghadir  
17 Dec 2006 majid ebrahimzadeh

i am engineering chemical

23 Aug 2005 Thomas Clark

What a good idea, I'm now using this format myself. One thing I'd suggest is the inclusion of a matlab Version, Release # and Service Pack # (I put it beneath the "Created On <date>" line).
Thankyou very much.

21 Dec 2004 muhammad harun

what a usefull software!

13 Aug 2004 Pascal Getreuer

Great idea -- I'm glad you took the time to put this together. Including "other m-files required" in a header had never occured to me, but sure makes sense. How would you extend this header format for functions with variable arguments?

Contact us