Documentatie

[VelhaChica]

Ik heb maar een heel korte vraag. Bestaat er een standaardmethode voor het documenteren van websites?

Ik beheer zelf een aantal websites, waar ik ook wat grafische vormgeving voor doe. Ik maak die veranderingen wel, maar ik weet niet hoe ik veranderen op een goede manier kan documenteren. Eigenlijk geldt dit voor meer zaken, zoals navigatie, gebruikte software, rechten e.d.

Met systeembeheer heb ik een standaardmethode, die erg gebaseerd is op o.a. Prince II. Daarin worden zaken als veranderingen, serverinrichting en rechten makkelijk weggeschreven.

Wellicht hoort dit niet hier thuis, maar ik vind het forum voor webdesign eigenlijk wel de aangewezen plek.

[PainkillA]

software architectuur = UML bijv. databases zijn ook al te modelleren. grafische dignen heb ik geen idee van. Of je bent mischien meer op zoek naar versiebeheer oid?

[ Voor 20% gewijzigd door PainkillA op 06-04-2008 20:49 ]

[VelhaChica]

Het gaat mij inderdaad meer om versiebeheer bij websites. Ik zocht dat woord.

[Borizz]

Kijk eens naar Subversion dat is een open source versie beheer systeem.

[VelhaChica]

Zoiets heb ik nu draaien. Maar naast de veranderingen in code, wil ik ook nog op papier iets over de veranderingen vertellen. Daar zoek ik dus een standaardmethodiek voor. Het moet zo zijn dat iemand met zo'n stuk papier mijn werk moet over kunnen nemen zonder eerst in de code te hoeven harken.

[--Niels--]

Als ik het goed begrijp wil je vooral de functionaliteiten vastleggen. Dat wordt volgens mij bij 'gewone' software vaak in een basisontwerp (is volgens mij ook een onderdeel van de watervalmethode) of functioneel ontwerp beschreven.
Je zou het eventueel ook nog in Use Case's kunnen beschrijven. Al zijn deze er meer op gericht dat een 'gewone' gebruiker het ook snapt. Als het doel meer een andere programmeur is, dan steek je al snel te veel tijd in het voor een ieder begrijpbaar maken. Met als resultaat dat een programmeur vaak snel even in de code kijkt om het te begrijpen.
Use Case beschrijft dus meer hoe de website het proces van de gebruiker ondersteunt, terwijl een Functioneel ontwerp/Basis ontwerp beschrijft, wat de invoer, bewerkingen en uitvoer van het programma zijn).

[alex3305]

Zelf doe ik altijd de volgende dingen;

• In mijn CSS zet ik de versie in nummers en datums. Dit geeft duidelijkheid van de laatste bijwerking en is ook duidelijk in welke versie je van de website hebt (ook als er bijv. een redesign is).
  Bijvoorbeeld: Versie: 1.0.06.0508
• Ook schrijf ik uitgebreide changelogs aan mijn klanten met welke veranderingen ik maak en ook waarom ik deze maak. Dit geeft duidelijkheid voor hun en ook voor mij. Hoe je dit moet schrijven is per persoon eigenlijk afhankelijk. Je kunt het doen in een [Bugfix]Beschrijving doen maar ook in een uitgebreide beschrijving.
• Schrijf ook voordat je met een project begint een document uit (uitgebreid) in wat je gaat veranderen en/of implenteren voor je klant. Deze kun je delen, maar ook voor jezelf houden. Daarnaast kun je de veranderingen in kleuren bijvoorbeeld bijhouden en onderin het documenten deze kleuren dan weer defineren. In dit document kun je onder andere opnemen: Wat er veranderd moet worden (mits er al een site bestaat), wat je gaat implenteren (software, scripting), wat je benodigheden zijn, wat de wensen en eisen van de klant zijn (eis moet eigenlijk altijd ingewilligd worden, wens niet per sé), wanneer de deadline is, wat je menu structuur is en zo kun je er nog meer inzetten.
• Naast deze tips, kan ik je nog maar één belangrijke tip geven, waar je wel aan gaat moeten wennen waarschijnlijk. Dat is namelijk; gebruik veel of in ieder geval genoeg comments in je code. Dit is belangrijk voor je zelf en kan af en toe ook verwarring voorkomen. Daarnaast kun je ook de site overdragen, mits dit moet.

Veel succes ermee, en als je er niet uitkomt, stuur me dan even een DM, dan kan ik je wel wat vedere informatie geven.

[TeeDee]

Alex3305 schreef op maandag 07 april 2008 @ 00:04:
Zelf doe ik altijd de volgende dingen;

• Naast deze tips, kan ik je nog maar één belangrijke tip geven, waar je wel aan gaat moeten wennen waarschijnlijk. Dat is namelijk; gebruik veel of in ieder geval genoeg comments in je code. Dit is belangrijk voor je zelf en kan af en toe ook verwarring voorkomen. Daarnaast kun je ook de site overdragen, mits dit moet.

Ik zou er van maken: Veel relevante comments. Iets als

C#:

/*
* Start Loop
* */
for(int i=0;i<10000;i++)
{
//do stuff
}
/*
* Finish Loop
* */

is voorzien van genoeg commentaar. Maar het is ook overduidelijk dat je een loop uit voert. Probeer in ieder geval je denkwijze te plaatsen. Waarom heb je voor dit gekozen en waarom voor dat.

Veel succes ermee, en als je er niet uitkomt, stuur me dan even een DM, dan kan ik je wel wat vedere informatie geven.

Lijkt me nu niet de insteek van een forum.

edit:
speciaal voor Suaver even duidelijkheid.

[Suaver]

Het schiet echt niet op om bij elke loop een "begin loop" en "end loop" te schrijven.

[moozzuzz]

Ik zou er van maken:

C#:

/*
* Doe 10000 stuffjes omwille van... te beginnen met i=0 (*)
* */
for(int i=0;i<10000;i++)
{
//do stuff
}
/*
* 10000 stuffjes gedaan, move on
*/

(*) Het is nuttiger te schrijven wat je wil doen (idee, principe, bedoeling, ... whatever) dan te schrijven dat het een loop is (dat begrijpt iedereen die voldoende kennis heeft, zoniet blijft ie er best sowieso af )

(**) Wat ik wel es handig vind zijn de einde scope's te becommentariëren omwille van het feit dat ik daar de draad wel es mis (het is zowat onmogelijk om alles perfect te indenten en van zodra je dit niet altijd doet loopt het wel ooit es mis).

my 2EUR hé

[TeeDee]

Hmm, ik geloof niet dat mijn betoog helemaal goed overgekomen is.

Maar het is ook overduidelijk dat je een loop uit voert. Probeer in ieder geval je denkwijze te plaatsen. Waarom heb je voor dit gekozen en waarom voor dat.

Trouwens:

(**) Wat ik wel es handig vind zijn de einde scope's te becommentariëren omwille van het feit dat ik daar de draad wel es mis (het is zowat onmogelijk om alles perfect te indenten en van zodra je dit niet altijd doet loopt het wel ooit es mis).

Nu weet ik niet wat jouw tools of the trade zijn, maar een fatsoenlijke IDE zorgt ervoor dat je code blocken (begin / eind van een method) kan inklappen. Bij notepad oid kan ik me voorstellen dat je wel eens het einde kwijt bent.

[ Voor 50% gewijzigd door TeeDee op 07-04-2008 18:28 ]

[dB90]

Kijk anders eens naar Trac daar kun je changes aan je code van commentaar voorzien etc. Als ik tenminste goed begrijp wat je bedoelt.

[eghie]

Voorbeeld van documentatie die ik voor een school opdracht heb gebruikt in JAVA:

Java:

/*
 * DBObject.java
 *
 * Created on 9 december 2007, 21:29
 */

package library;

import java.util.Observable;

/**
 * Dit is een database object. Elke instantie van deze klasse heeft zijn data opgeslagen in de database.
 * Ook maakt deze klasse gebruik van het Observer pattern, wat inhoud dat bij elke verandering aan de klasse,
 * de verandering wordt gemeld aan alle observers, die lid zijn van deze klasse. Zie ook: {@link http://nl.wikipedia.org/wiki/Observer}
 *
 * @see {@link http://nl.wikipedia.org/wiki/Observer}
 * @author eghie
 */
public abstract class DBObject extends Observable {
    protected int id;

    /**
     * Maakt een nieuwe instantie van DBObject.
     */
    public DBObject() {
    }

    /**
     * Met deze methode geef je aan dat de data in deze klasse is veranderd.
     * Na uitvoer deelt hij alle observers mee, dat de data is vervangen via observer.update(this);.
     */
    protected void isChanged() {
        this.setChanged();
        this.notifyObservers();
    }
    
    /**
     * Geeft het database ID van het object terug.
     *
     * @return de database ID van het object
     */
    public int getID() {
        return this.id;
    }

    /**
     * Wijzigd de database ID van het object.
     * 
     * @param value een int die het nieuwe ID moet voorstellen
     * @alert Waarde moet groter zijn dan 0, anders is het geen geldig id.
     * @alert De id mag ook maar alleen voor de 1e keer geset worden.
     */
    public void setID(int value) {
        if (value > 0 && this.id == 0)
            this.id = value;
    }
    
}

en:

Java:

/*
 * Database.java
 *
 * Created on 29 november 2007, 21:47
 */

package library;
import java.sql.*;
import java.text.ParseException;
import java.text.SimpleDateFormat;

/**
 * Deze database klasse regelt alle communicatie tussen de database en de applicatie.
 * 
 * @author eghie
 */
public class Database {
    private Connection connection;
    public static Database dbcon = null;
    private boolean connected = false;
    
    private String dburi = "jdbc:odbc:muziekcon";
    private String dbuser = "";
    private String dbpass = "";

    /**
     * Maakt intern een nieuwe instantie van Database. Het bereid ook wat gegevens voor, voor de klasse.
     */
    private Database() {
    }
    
    /**
     * Dit object is een singleton, dit is gedaan omdat er maar 1 database verbinding nodig is binnen de applicatie.
     * Daarintegen kan Access ook niet zoveel verbindingen aan.
     * 
     * @return de instantie van de klasse
     */
    public static Database getInstance() {
        if (Database.dbcon instanceof Database)
            return Database.dbcon;
        
        Database.dbcon = new Database();
        
        return Database.dbcon;
    }

    /**
     * Deze methode zorgt ervoor dat er een verbinding wordt gemaakt met de database.
     *
     * @return een boolean of de verbinding wel goed is gegaan of niet
     */
    public boolean connect() {
        if (this.connected)
            return true;

        try {
            Class.forName("sun.jdbc.odbc.JdbcOdbcDriver");
            try {
                this.connection = DriverManager.getConnection(this.dburi, this.dbuser, this.dbpass);
            } catch (SQLException ex) {
                ex.printStackTrace();
                return false;
            }
        } catch (ClassNotFoundException ex) {
            ex.printStackTrace();
            return false;
        }

        this.connected = true;

        return true;
    }

    /**
     * Deze methode zorgt ervoor dat de verbinding met de database wordt verbroken.
     */
    public void disconnect() {
        try {
            this.connection.close();
        }
        catch (Exception e) {
        }

        this.connection = null;
        this.connected = false;
    }

    /**
     * De destructor variant in JAVA. Deze functie wordt uitgevoerd net voordat de Garbage Collector hem opruimt.
     * Voor meer info zie: {@link http://en.allexperts.com/q/Java-1046/Constructor-destructor.htm}
     *
     * @see {@link http://en.allexperts.com/q/Java-1046/Constructor-destructor.htm}
     */
    protected void finalize() throws Throwable {
        this.disconnect();
    }

    /**
     * Voert de query uit op de database en geeft de resultset terug.
     *
     * @param query een string die de query bevat
     * @return de resultset die terug komt van de database, of null bij een fout
     */
    public ResultSet execQuery(String query) {
        try {
            Statement smt = this.connection.createStatement();

            if (smt == null)
                return null;

            return smt.executeQuery(query);
        }
        catch (SQLException e) {
                e.printStackTrace();
                return null;
        }
        catch (Exception e) {
                e.printStackTrace();
                return null;
        }
    }

    /**
     * Voert de update/insert/delete query uit op de database en geeft aan of het gelukt is of niet.
     * Dit is een aparte functie, omdat deze queries een andere resultaat opleveren dan een select query.
     *
     * @param query een string die de query bevat
     * @return het aantal rijen wat aangepast is, of -1 bij een fout.
     */
    public int execUpdate(String query)
    {
        try {
            Statement smt = this.connection.createStatement();

            if (smt == null)
                return -1;

            return smt.executeUpdate(query);
        }
        catch (SQLException e) {
            e.printStackTrace();
            return -1;
        }
        catch (Exception e) {
            e.printStackTrace();
            return -1;
        }
    }

    /**
     * Zet java Date om maar een SQL datum.
     *
     * @param val een Date
     * @return een String die de SQL datum bevat.
     */
    public String toSQLDate(java.util.Date val) {
        SimpleDateFormat dateformat = new SimpleDateFormat("yyyy-MM-dd");

        return dateformat.format(val);
    }
    
    /**
     * Zet SQL datum om naar java Date.
     *
     * @param val een String die de SQL datum bevat
     * @return een Date, of null bij een parsefout
     */
    public Date fromSQLDate(String val) {
        SimpleDateFormat dateformat = new SimpleDateFormat("yyyy-MM-dd");
        
        try {
            return (Date) dateformat.parse(val);
        } catch (ParseException ex) {
            return null;
        }
    }
   
}

Let maar even niet op de code. Ik weet dat hij bijvoorbeeld gevoelig is voor SQL injection, etc. Spoed klusje was het ook.

[ Voor 74% gewijzigd door eghie op 07-04-2008 19:03 . Reden: code ingekort ]