Ein Script schreiben, Dokumentation, Teamarbeit Tutorial.

Hilfreiche Erklärungen und Tipps zum Lernen von Autohotkey

Moderator: jNizM

User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Ein Script schreiben, Dokumentation, Teamarbeit Tutorial.

23 Oct 2013, 13:58

Hi ich arbeite seit eine Weile ja an meiner 2D Gameengine.
Im zuge der DAE Idee habe ich vorgeschlagen ein größeres Projekt in der AHK community öffentlich und für jedermann ersichtlich im team fertigzustellen.
Da sich dieses Projekt einigermaßen gut dafür eignet würde ich vorschlagen, dass wir dieses Projekt in der deutschen AHK community fertigstellen.
Ich wollte vorher aber Fragen wer gerne teilnehmen würde.
Also wer hat Zeit langeweile auf der Arbeit eh nichts zu tun (ist Beamter oder ähnliches) und hat Lust teilzunehmen.
Generell gibt es unmengen an Arbeit und verschiedene Arbeitsbereiche, von einfach bis schwer.
Ich wäre dafür das Projekt auf Github zu verwirklichen, habe aber auch nichts gegen eine Forum interne Lösung.
Recommends AHK Studio
Alibaba
Posts: 480
Joined: 29 Sep 2013, 16:15
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

23 Oct 2013, 14:55

Bin dabei.
Wie das ganze erfolgt, ist mir dabei egal... :D
"Nothing is quieter than a loaded gun." - Heinrich Heine
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

23 Oct 2013, 15:03

Dich hatte ich sogar schon eingeplant :D
Recommends AHK Studio
just me
Posts: 9407
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

24 Oct 2013, 01:04

Tut mir leid. Ich halte Gameengines in AHK bisher eher für Machbarkeitsstudien als für erfolgversprechende Projekte. Außerdem ist das nicht mein Metier. Ich werde mir das aber anschauen und mich melden, falls ich etwas beitragen kann.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

24 Oct 2013, 05:23

Dokumentation:
Wir müssen uns standardmäßig auf eine Dokumentationsweise einigen.
Ich bevorzuge diese Methode selbst wenn es länger dauert:

Code: Select all

/*
HeapFunktionen:
Diese Funktionen geben Kontrolle über den Speicher den ein Programm erhält.
Man kann so z.B. einfach neuen Speicher anfordern löschen oder die Länge bestimmen.
Siehe:
http://msdn.microsoft.com/en-us/library/aa366711(v=vs.85).aspx
*/


/*
HeapAlloc(Size)
   Erstellt einen neuen Speicherbereich mit der gewünschten größe und gibt die Start Adresse zurück.
   Size: die Größe des neuen Speicherbereichs in bytes.
   Return: der Pointer auf den Speicherbereich.
Benutze Funktionen:
HeapAlloc: Die Hauptfunktion. 
http://msdn.microsoft.com/en-us/library/windows/apps/aa366597(v=vs.85).aspx
GetProcessHeap: Funktion um auf den Process Heap zugreifen zu können.
http://msdn.microsoft.com/en-us/library/windows/apps/aa366569(v=vs.85).aspx
*/


HeapAlloc(Size)
{
	return DllCall("HeapAlloc","Ptr",DllCall("GetProcessHeap"),"UInt",8,"Ptr",size,"ptr")	
}


/*
HeapReAlloc(ptr,Size)
  Funktion um die Größe eines bereits erstellten Speicherbereichs zu verändern.(Daten bleiben erhalten)
  ptr: der Pointer auf den Speicherbereich kann z.B. durch die HeapAlloc funktion zurückgegen werden.
  Size: die neue Größe des Speicherbereichs in bytes.
  Return: der Pointer auf den Speicherbereich mit der neuen größe.
Benutze Funktionen:
HeapReAlloc: Die Hauptfunktion. 
http://msdn.microsoft.com/en-us/library/windows/apps/aa366704(v=vs.85).aspx
GetProcessHeap: Funktion um auf den Process Heap zugreifen zu können.
http://msdn.microsoft.com/en-us/library/windows/apps/aa366569(v=vs.85).aspx
*/


HeapReAlloc(ptr,Size)
{
	return DllCall("HeapReAlloc","Ptr",DllCall("GetProcessHeap"),"UInt",8,"Ptr",ptr,"Ptr",Size)
}


/*
HeapSize(ptr)
  Funktion um die Größe eines bereits erstellten Speicherbereichs zu bestimmen.
  ptr: der Pointer auf den Speicherbereich kann z.B. durch die HeapAlloc funktion zurückgegen werden.
  Return: die Größe des Speicherbereichs in Bytes. 
Benutze Funktionen:
HeapSize: Die Hauptfunktion. 
http://msdn.microsoft.com/en-us/library/windows/apps/aa366706(v=vs.85).aspx
GetProcessHeap: Funktion um auf den Process Heap zugreifen zu können.
http://msdn.microsoft.com/en-us/library/windows/apps/aa366569(v=vs.85).aspx
*/


HeapSize(ptr)
{
	return a:=DllCall("HeapSize","Ptr",DllCall("GetProcessHeap"),"UInt",8,"Ptr",ptr)
}


/*
HeapFree(ptr)
  Funktion um einen Speicherbereich freizugeben.(löschen)
  ptr: der Pointer auf den Speicherbereich kann z.B. durch die HeapAlloc funktion zurückgegen werden.  
  Return: Wenn die Funktion erfolgreich ist dann 0
Benutze Funktionen:
HeapFree: Die Hauptfunktion. 
http://msdn.microsoft.com/en-us/library/windows/apps/aa366701(v=vs.85).aspx
GetProcessHeap: Funktion um auf den Process Heap zugreifen zu können.
http://msdn.microsoft.com/en-us/library/windows/apps/aa366569(v=vs.85).aspx
*/


HeapFree(ptr)
{
	return DllCall("HeapFree","Ptr",DllCall("GetProcessHeap"),"UInt",8,"Ptr",ptr)
}


/*
RtlMoveMemory(dptr,sptr,length) Diese Funktion kopiert bytes. Die Herkunft und das Ziel können sich sogar überlappen.
  dptr: die Herkunft(Pointer)
  sptr: das Ziel (Pointer)  
  Length: die Länge der zu kopierenden bytes.
  Return: nichts.
Benutze Funktionen:
RtlMoveMemory: Die Hauptfunktion.
http://msdn.microsoft.com/en-us/library/windows/desktop/aa366788(v=vs.85).aspx
*/


RtlMoveMemory(dptr,sptr,length)
{
	DllCall("RtlMoveMemory","ptr",dptr,"ptr",sptr,"ptr",length)
}


/*
HeapCreateCopy(srcptr)
  Funktion um eine Kopie eines Speicherbereichs zu erstellen.
  srcptr: der Pointer auf den Speicherbereich kann z.B. durch die HeapAlloc funktion zurückgegen werden.  
  Return: der Pointer auf den neuen Speicherbereich mit dem selben Inhalt wie der alte.
Benutze Funktionen:
HeapSize: Um die Größe des zu kopierenden Speicherbereichs zu ermitteln.
HeapAlloc: Um einen neuen SpeicherBereich mit der selben Größe zu erstellen
RtlMoveMemory: Um die Daten des alten SpeicherBereichs in den neuen zu verschieben. 
*/


HeapCreateCopy(srcptr)
{
	ptr:=HeapAlloc(size:=HeapSize(srcptr))
	RtlMoveMemory(ptr,sourceptr,size)
	return ptr
}


/*
HeapInsert(ptr,val,type="ptr")
  Funktion um neue Daten an einen Speicherbereich anzuhängen. Es wird ein enuer erstellt falls noch kein Pointer angegeben wurde.
  ptr: der Pointer auf den Speicherbereich kann z.B. durch die HeapAlloc funktion zurückgegen werden.  
  val: die Daten
  type="ptr": der Typ der Daten (DllCall typen). Standardmäßig ist ptr vorgegeben.
  Return: der Pointer auf den neuen erweitereten Speicherbereich.
Benutze Funktionen:
HeapSize: Um die Größe des Speicherbereichs zu ermitteln.
HeapAlloc: Um einen neuen Speicherbereich zu erstellen, wenn noch keiner vorhanden ist.
HeapReAlloc: Um den Speicherbereich vergrößern.
NumPut: Um die Daten am Ende des vergrößerten Speicherbereich einzufügen.
*/


HeapInsert(ptr,val,type="ptr")
{
static f:={UInt:4,Int:4,UPtr:A_PtrSize,Ptr:A_PtrSize,Float:4,Double:8,UChar:1,Char:1,UShort:2,Short:2,Int64:8}
    If (ptr)
    {
	size:=HeapSize(ptr)
	ptr:=HeapReAlloc(ptr,size+f[type])	
	}
	Else
	ptr:=HeapAlloc(f[type]),size:=0
	numput(val,(ptr+0),size,type)
	return ptr
}


/*
HeapRemove(ptr,offset=0,type="ptr")
  Funktion um ein Stück Daten aus einem Speicherbereich zu entfernen. Wenn das letzte Stück Daten entfernt wird, wird der Speicherbereich freigegeben (gelöscht).
  ptr: der Pointer auf den Speicherbereich kann z.B. durch die HeapAlloc funktion zurückgegen werden.  
  val: offset Startpunkt der Daten
  type="ptr": der Typ der Daten (DllCall typen). Standardmäßig ist ptr vorgegeben.
  Return: der Pointer auf den neuen verkürzten Speicherbereich./0 Wenn dieser nicht mehr vorhanden ist
Benutze Funktionen:
HeapSize: Um die Größe des Speicherbereichs zu ermitteln.
RtlMoveMemory: Um die Daten die hinter den Daten liegen, die entfernt werden sollen weiter nach vorne zu Bewegen.
HeapFree: um den Speicherbereich eventuell freizugeben.
HeapReAlloc: Um den Speicherbereich verkleinern.
*/


HeapRemove(ptr,offset=0,type="ptr")
{
static f:={UInt:4,Int:4,UPtr:A_PtrSize,Ptr:A_PtrSize,Float:4,Double:8,UChar:1,Char:1,UShort:2,Short:2,Int64:8}
	size:=HeapSize(ptr)
	If (size-(offset+f[type]))
	    RtlMoveMemory(ptr+offset,ptr+offset+f[type],size-(offset+f[type]))
	If !(size-f[type])
		return HeapFree(ptr)
	return HeapReAlloc(ptr,size-f[type])
}]
Recommends AHK Studio
User avatar
jNizM
Posts: 3183
Joined: 30 Sep 2013, 01:33
Contact:

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

24 Oct 2013, 06:14

Schau dir mal die UDF-Aufbauweise von AutoIt an

hier noch ein Beispiel aus den Includes _ColorSetRGB
[AHK] v2.0.5 | [WIN] 11 Pro (Version 22H2) | [GitHub] Profile
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

24 Oct 2013, 06:57

Heißt das jetzt du machst mit?
Recommends AHK Studio
User avatar
hoppfrosch
Posts: 443
Joined: 07 Oct 2013, 04:05
Location: Rhine-Maine-Area, Hesse, Germany
Contact:

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

24 Oct 2013, 07:21

Ich bin nicht dabei (too much things to do - too less time) :) , möchte aber trotzdem kurz meinen Senf zu nnik's Doku-Vorschlag geben:

Überlegt zu welchem Zweck die Dokumentation dienen soll - in der Regel sind zwei Hauptzwecke damit verbunden:
* "Benutzerdokumentation" - dort wird in der Regel dokumentiert, was jemand wissen muss, der die Funktion nutzen will (z.Bsp Zweck der Funktion, Ein-/Rückgabeparameter)
* "Entwicklerdokumentation" - Beschreibung von (nicht trivialen) Implementierungsdetails (z.B. "Was passiert in dieser komplizierten FOR-Schleife?")

Ich versuche bei mir beide getrennt zu halten: im Funktionsheader habe ich in der Regel die "Benutzerdokumentation" (Beschreibung des Interface) in einer Form, in der ich mit Tools einfach eine externe (z.B HTML-) Dokumentation ableiten kann (Tools: doxygen, NaturalDocs oder GenDocs ...). Die Benutzerdokumentation sollte für alle Entwickler standardisiert sein. Die Entwicklerdokumentation erfolgt hingegen mit Standardkommentaren im Code direkt ... (mit evtl persönlicher Handschrift des Entwicklers)

Bei nniks Bsp sind beide Typen etwas vermischt:

Code: Select all

/*
HeapFree(ptr)
  Funktion um einen Speicherbereich freizugeben.(löschen)
  ptr: der Pointer auf den Speicherbereich kann z.B. durch die HeapAlloc funktion zurückgegen werden.  
  Return: Wenn die Funktion erfolgreich ist dann 0
Benutze Funktionen:
HeapFree: Die Hauptfunktion.
http://msdn.microsoft.com/en-us/library/windows/apps/aa366701(v=vs.85).aspx
GetProcessHeap: Funktion um auf den Process Heap zugreifen zu können.
http://msdn.microsoft.com/en-us/library/windows/apps/aa366569(v=vs.85).aspx
*/
Was interessiert einen möglichen Benutzer der Funktion HeapFree welche Funktionen intern aufgerufen werden? Das gehört für mich eigentlich in die Entwicklerdoku ...
Last edited by hoppfrosch on 24 Oct 2013, 07:25, edited 1 time in total.
User avatar
jNizM
Posts: 3183
Joined: 30 Sep 2013, 01:33
Contact:

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

24 Oct 2013, 07:23

Ich bin zzt mit Dll's beschäftigt :D
Das war nur ein Hinweis, wie man das ganze einheitlich (mit Struktur) aufbauen kann.
[AHK] v2.0.5 | [WIN] 11 Pro (Version 22H2) | [GitHub] Profile
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

24 Oct 2013, 10:39

Nun ja das sind ja auch nicht Benutzerdokumentationen.
In diesem Fall sind es nur interne Funktionen.
Das Benutzer Interface ist viel einfacher.
Recommends AHK Studio
Alibaba
Posts: 480
Joined: 29 Sep 2013, 16:15
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

25 Oct 2013, 05:39

Ich persönlich würde eine strikte Dokumentation nur für die Endnutzerfunktionen des Interfaces vorschlagen. Diese sollten dann die AutoIt UDF Dokumentationsweise, welche von jNizM vorgeschlagen wurde, als Vorbild haben, also in etwa so:

Code: Select all

; #FUNCTION# ;===============================================================================
;
; Name...........: _DateDiff
; Description ...: Returns the difference between 2 dates, expressed in the type requested
; Syntax.........: _DateDiff($sType, $sStartDate, $sEndDate)
; Parameters ....: $sType - One of the following:
;                  |D = Difference in days between the given dates
;                  |M = Difference in months between the given dates
;                  |Y = Difference in years between the given dates
;                  |w = Difference in Weeks between the given dates
;                  |h = Difference in hours between the given dates
;                  |n = Difference in minutes between the given dates
;                  |s = Difference in seconds between the given dates
;                   $sStartDate  - Input Start date in the format "YYYY/MM/DD[ HH:MM:SS]"
;                   $sEndDate    - Input End date in the format "YYYY/MM/DD[ HH:MM:SS]"
; Return values .: Success - Difference between the 2 dates.
;                  Failure - Returns 0 and Sets @Error:
;                  |0 - No error.
;                  |1 - Invalid $sType
;                  |2 - Invalid $sStartDate
;                  |3 - Invalid $sEndDate
; Author ........: Jos van der Zande
; Modified.......:
; Remarks .......:
; Related .......: _DateAdd
; Link ..........;
; Example .......; Yes
;
; ;==========================================================================================
Func _DateDiff($sType, $sStartDate, $sEndDate)
...
Die Dokumentationen für interne Funktionen, welche nur für Entwickler dienlich sind, können meiner Meinung nach ruhig die "Handschrift" des jeweiligen Erstellers tragen, sollten allerdings in jedem fall vorhanden sein.
"Nothing is quieter than a loaded gun." - Heinrich Heine
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

25 Oct 2013, 09:16

Für die Endnutzerfunktionen werde ich mehr als eine einfache Dokumentation schreiben ich dachte da an eine Hilfedatei + Tutorial.
Recommends AHK Studio
Alibaba
Posts: 480
Joined: 29 Sep 2013, 16:15
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

25 Oct 2013, 10:14

nnnik wrote:Für die Endnutzerfunktionen werde ich mehr als eine einfache Dokumentation schreiben ich dachte da an eine Hilfedatei + Tutorial.
Naja, das wäre ja noch besser. :D
Heißt das jetzt, dass sich deine eigentliche Forderung nach einer einheitlichen Dokumentation nur auf die internen Funktionen bezieht?
"Nothing is quieter than a loaded gun." - Heinrich Heine
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

25 Oct 2013, 10:43

Ja das ist Teil der Teamarbeit.
Zudem soll ja jeder einigermaßen auch den Code verstehen.
Recommends AHK Studio
Alibaba
Posts: 480
Joined: 29 Sep 2013, 16:15
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

25 Oct 2013, 16:43

Ok.
In dem Fall wäre meiner Meinung nach eine Verbindung aus der von dir vorgeschlagenen Methode (zur generellen Beschreibung der Funktion) und den inline-Kommentaren (zur Erklärung interner Strukturen) am besten.
"Nothing is quieter than a loaded gun." - Heinrich Heine
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

03 Nov 2013, 08:11

Also wir brauchen noch jemanden sonst lohnt sich ein Teamwork projekt eig. nicht.
Recommends AHK Studio
Alibaba
Posts: 480
Joined: 29 Sep 2013, 16:15
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

03 Nov 2013, 08:13

Ich hätte auch nichts dagegen, wenn wir mit Leuten aus der englischen Community zusammenarbeiten.
Dann müssen wir die Doku halt auf Englisch anlegen...
"Nothing is quieter than a loaded gun." - Heinrich Heine
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

03 Nov 2013, 08:19

Jo OK hört sich nicht schlecht an.
Recommends AHK Studio
Bentschi
Posts: 22
Joined: 02 Oct 2013, 18:45

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

04 Nov 2013, 09:15

Erst war ich unsicher, da ich kein Beamter bin, aber wäre doch gerne dabei.
Natürlich nur für Hirnschmalzvorderndes, aber leider auch nur ab und zu mal eben ein paar 100 Zeilen oder so (enger Zeitplan).
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Ein Script schreiben, Dokumentation, Teamarbeit Tutorial

04 Nov 2013, 09:36

das ist natürlich super gut weil du dich garantiert mit OpenAL auskennst, oder?
Recommends AHK Studio

Return to “Tutorials”

Who is online

Users browsing this forum: No registered users and 14 guests