SitePoint Sponsor

User Tag List

Results 1 to 3 of 3
  1. #1
    SitePoint Evangelist
    Join Date
    May 2006
    Posts
    424
    Mentioned
    2 Post(s)
    Tagged
    0 Thread(s)

    Advice on file header

    Since I've switched to classes my code is more reusable and I've developed a framework of sorts. I'd like to comment up the files properly so wanted your opinions on what to include. Based on PEAR I have this:

    PHP Code:
    /*!
     *
     * File/Class Name
     *
     * File/Class Description
     *
     * Author              My Name | www.mywebsite.co.uk
     * Version             1.0
     * Last Updated        7 September 2013
     *
     * @vendor  VendorName
     * @package PackageName
     *
     * Released under the MIT license
     * Copyright (c) 2013 My Name | www.mywebsite.co.uk
     * 
     * Permission is hereby granted, free of charge, to any person obtaining a copy
     * of this software and associated documentation files (the "Software"), to deal
     * in the Software without restriction, including without limitation the rights
     * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     * copies of the Software, and to permit persons to whom the Software is
     * furnished to do so, subject to the following conditions:
     * 
     * The above copyright notice and this permission notice shall be included in
     * all copies or substantial portions of the Software.
     * 
     * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
     * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
     * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
     * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
     * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
     * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
     * THE SOFTWARE.
     *
     */ 
    Do you think it's overkill to put the license in each file? I notice some do this but JQuery, for example, just has a link to the license on their site and Symfony tells them to read the file.

    Have I missed anything out?

    I don't use Git yet though plan to lean. One additional thing I'd like to know is: if you're not using version control how to do you keep track of what was added, removed and fixed in each version? Do you just keep a text file logging everything?

    Thanks.

  2. #2
    Programming Team silver trophybronze trophy
    Mittineague's Avatar
    Join Date
    Jul 2005
    Location
    West Springfield, Massachusetts
    Posts
    16,494
    Mentioned
    164 Post(s)
    Tagged
    1 Thread(s)
    IMHO each file should at least state which license it is under and have a link to an online copy.

    I suppose the text isn't all that much, but I think what I would do is include it if the file might be used stand-alone otherwise put it in a separate text file if it's part of a package.

    I never really paid notice to how often any license changed, and I don't know if software written under one version is "stuck" or if newer versions supercede the original older version.

    I have put changelogs in the head comments before, but that can get lengthy in time so now I keep them in separate changelog files.

  3. #3
    SitePoint Evangelist
    Join Date
    May 2006
    Posts
    424
    Mentioned
    2 Post(s)
    Tagged
    0 Thread(s)
    Good advice, thanks.


Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •