freenode/#lisp - IRC Chatlog
Search
19:11:22
beach
It is too late for me. I need to go spend time with my (admittedly small) family. I'll look tomorrow morning (UTC+1).
20:07:38
aeth
ebrasca: From a previous conversation here on docstrings, I came up with this rule for my projects: "Docstrings for functions and methods should mention the inputs, the outputs, and the side effects."
20:12:13
aeth
so e.g. your read-file currently says "Return data buffer of file", but that's only the outputs part (except, I guess it mentions the variable file?)
20:19:11
aeth
The ones I've seen usually have the first line line up with the function indentation and then the rest aren't indented.
20:19:14
pjb
the problem is that the string itself is indented. SO when multiline, I usually start it with a newline (and end it similarly).
20:20:55
aeth
ebrasca: " RET type your documentation RET type your documentation RET type your documentation RET "
20:26:46
aeth
ebrasca: Here's an elaborate example of what pjb's style is, from pjb's own code: https://gitlab.com/com-informatimago/com-informatimago/blob/51d8149b18cdce4626c1d795181d9232c465c883/rdp/rdp-macro.lisp#L48-208
20:27:30
aeth
Notice that the first " lines up with the source indentation and then the rest start at column 0
20:28:19
aeth
ebrasca: Side effects would be on something like format, where what format t does depends on *standard-output*
20:30:42
aeth
Okay, I'm actually not sure if interacting with an outside global is a side effect or an input, actually.
20:31:05
aeth
I think setting it might be a side effect, but reading it might be an input. So my format example might be bad.
20:33:36
aeth
ebrasca: In some sense, "good code is better than documentation" is true, but not in the way you think it is. I think it applies more to comments than to docstrings. If you have to comment some part of your code heavily, you can probably just write it better and not have to comment that part.
20:34:19
aeth
But you can't really do that with variable names themselves unless you make their names very long and ugly.
20:38:14
aeth
There is nothing stopping you from writing a mini-hyperspec in docstrings, complete with examples, etc. People would probably like that. You would probably need some markup convention for that, though. e.g. Python uses reStructuredText and Java uses JavaDoc
20:38:31
aeth
What I gave is the minimum documentation you need to give in a docstring, not the maximum.
20:39:19
aeth
Doing something equivalent to docstrings in variable names would (1) capture only the minimum part, (2) look ugly, (3) violate CL style guidelines
20:40:17
aeth
ebrasca: Well, some programmers in other programming languages used concise conventions so they could have their self-documenting variable names while not greatly lengthening their variable names. e.g. https://en.wikipedia.org/wiki/Hungarian_notation
20:42:44
puchacz
like here: void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
20:48:00
puchacz
Bike: so defcalback first, and it should take :pointer as an argument and return :void, right?
20:48:36
Bike
borei: you mean, you tried to use this as a specializer? in the defmethod lambda list?
20:49:02
borei
(defmethod (setf translate) ((r '(simple-array double-float (4))) (transform transform-3d)) ..... )
20:49:12
Bike
borei: point one, don't quote it. point two, not all types are specializers. that type is not a specializer.
20:49:17
aeth
ebrasca: You have to have docstrings for every exported function in most styles. For the other functions, it depends on the style.
20:51:55
aeth
Something like a make-foo could possibly be documented in one line: "Returns a newly allocated foo based on the filename file and the number number"
20:53:20
aeth
If you had a formal style for your docstrings, it would probably make them take up several lines at a minimum.
20:56:18
aeth
A lot of the tile you might say things like "the number number" in your docstring because your variable name for the input is perfectly named. Sometimes people capitalize the names to make it look a little better, i.e. "the number NUMBER"
21:01:07
puchacz
Bike: FYI, changing the argument type from :pointer to :int of sqlite3-result-text lets me pass -1 and it seems to work.....
21:04:00
puchacz
I think "casting" to function pointer does not do anything in C to actual bitpattern of data in memory..... but I may be wrong, as I don't know C
21:18:15
pjb
ebrasca: yes: basically all that you put in the docstring, you could put it in a declare.
21:28:10
TMA
ebrasca: the main thing is that you can ignore most (if not all) of the declarations except for (declare (special ...))
21:55:06
pjb
This is why it's important to also write the tools that will interpret your custom declarations.
21:55:30
pjb
Then you can call them automatically in your build process, and fail when there are errors.
21:56:07
pjb
For example, those pre- and post-condition can be used to generate assertions and use them in tests or in the compiled code.
22:13:51
pjb
I use the stepper declaration to disable the stepper in some functions that cannot be stepped (eg. the functions that are called from the stepper itself or that are too much of a bore to step into).
22:15:45
pjb
ebrasca: elsewhere, I've used declare to declare commands (interactive functions). In emacs lisp, (interactive) is a declaration. In CL You write (declare (interactive)).
22:16:14
pjb
ebrasca: (of course, you can also use a macro such as defcommand in those cases, sometimes it's easier than to process declarations).
23:01:31
aeth
If someone was going to add a contract system to CL it would be nice for the type part of it to use type declarations in SBCL and any other CL that uses similar semantics and check-type for the majority of implementations.
23:02:36
mgsk
jmercouris: seeing weird behaviour of tabs in gtk. Sometimes C-x b doesn't show any tabs, and C-[ shows empty pages. Aware of that?
23:02:48
aeth
(I'm assuming a contract system in CL would do both runtime type checking and compile time type checking.)
23:07:07
jmercouris
mgsk: as a quick aside, if c-x b doesn't show any tabs, type space, and then backspace, it'll refresh the table view, usually :D
23:10:15
jmercouris
I don't think that should have an effect, though the stupidity of GTK has surprised me quite a bit :D
23:13:36
jmercouris
except for using the legacy webkit wrappers on cocoa, hopefully with a new ffigen replacment that can be fixed
23:15:12
jmercouris
I tried installing BSD on my macbook for dual boot, I ended up in tears from frustration
23:16:01
isBEKaml
Surely, you shouldn't have problems installing any BSD on a Mac? Because Mac is derived from BSD?
23:17:11
jmercouris
darwin has diverged quite a bit from straight bsd, at least apple isn't freely handing out kexts
23:20:47
p_l
OSX is derived from OPENSTEP which was derived from NEXTSTEP which is most closely related to OSFMK which is related to original "Mach Unix" in turn related to BSD4
23:24:37
jmercouris
these days though, technically a Mach kernel, I believe they use shared memory for IPC, which technically disqualifies it
23:26:04
p_l
jmercouris: message passing over bits of memory that were shared and unshared using MMU
23:28:53
isBEKaml
p_l: I didn't really read much into the MacOS (X) divergence. I knew there was NextStep somewhere in its heritage, but NS was derived from BSD line. I don't recall reading about OSFMK -- I'll look that up, thanks
23:29:43
p_l
isBEKaml: NS was derived from Mach, and cross-pollinated with OSF/1 mostly, which was BSD-oriented "counter" to AT&T SysV
23:32:50
p_l
there's actually a Mach 4, because development didn't end when CMU released 3.0. OSFMK which started on 2.5, continued to take code from 3.0 and later projects, including a lot of contribution of their own. Mach 4.0 created also official interface for "colocation" i.e. starting servers in kernel space
23:34:45
p_l
after Mach 3, the research work turned towards more hybrid approaches, especially as Mach IPC security... was problematic for performance
23:41:45
p_l
OSFMK was a "pragmatic" system that didn't discard syscalls etc. and incorporated things from newer research, while post-CMU Mach4 project reintroduced formal apis for colocation
4:07:16
Colleen
beach: drmeister said 2 hours, 5 minutes ago: In cstify.lisp it looks like there is a redundant (cstify (cdr list)) - is that the case?
4:09:33
beach
ebrasca: You can avoid ugly docstrings in code by using #.(format nil "...") Then you can use the ~@ format directive that lets you indent the next line in the source code, but that indentation is not part of the string.
4:11:40
beach
ebrasca: I have said this before, but I'll say it again: docstrings are typically meant for the user and not for the maintainer, but they are in a place where the user does not look and the maintainer has to. Therefore they are noise in the source code. For that reason, I use (SETF DOCUMENTATION) intsead and I put the docstrings in a separate file.
4:21:43
beach
ebrasca: It is preferable to use signals other than simple errors so that client code can catch the errors by type. It is also great to provide restarts, so that client code can communicate with the library and invoke possible ways to continue.