[Info-vax] openvms and xterm
Dave Froble
davef at tsoft-inc.com
Fri May 3 13:17:36 EDT 2024
On 5/3/2024 11:41 AM, Arne Vajhøj wrote:
> On 5/3/2024 10:16 AM, Dave Froble wrote:
>> On 5/3/2024 8:03 AM, chrisq wrote:
>>> Yes, it's the fashion
>>> to write commentless code these days,
>>
>> Since when?
>>
>> If so, then things are worse than I could imagine.
>
> I will claim that the "recommended approach"
> today actually is to use comments.
>
> Clean Code, Code Complete etc..
>
> Note though that there is a strong focus on useful
> comments vs useless comments.
>
> Useless comments are comments that explains what
> the code does, but if the reader knows the programming
> language, then those are redundant because the code
> already provide that information, and they are in fact
> bad because they clutter up the code.
>
> Useful comments are comments that explain why the code
> does what it does.
>
> Super simple example useless:
>
> // add 1 to ix
> ix = ix + 1
>
> Super simple example useful:
>
> // skip separating comma
> ix = ix + 1
>
> But "recommended approach" and "used everywhere" are
> of course two different things.
>
> In general the overall picture of software quality is
> very mixed. Some good, a lot ok and some bad. Maybe
> even a lot bad.
>
> The number of software developers has increased x10 or more.
> And no surprise the average skill level of 30 million
> software developers are lower than than of 3 million software
> developers.
>
> Current fashions in development methodologies does not
> favor strict processes.
>
> There may also be a generational thing of "I will do as
> I am told" vs "I will do as I want to".
>
> So in the real world some write useless comments because
> they don't know better, some write no comments because
> they can get away with it and some write no comments
> because the feel very cool by proclaiming that
> "code should be self-explanatory".
>
> And some still write useful comments because they got it.
>
> Arne
>
Well, we've now endured weeks of discussion about Unix, Linux, systemd, and
such, on c.o.v, so while the following could be considered rather verbose, I'm
not going to feel the following is useless spamming of the group.
:-)
The following is some snippets from what was basically a research program, and I
consider commenting such should be rather terse. For production programs I'd
want a lot more.
First, declare the purpose. Shouldn't this always be done?
!********************************************************************
!
! Program: TCP_PEEK.BAS
! Function: Test Using TCP/IP Sockets as a Listener
! Version: 1.00
! Created: 01-Dec-2011
! Author(s): DFE
!
! Purpose/description:
!
! This program will set up TCP/IP sockets to allow
! itself to listen for connection requests. When
! a connection request is received, this program
! will accept the connection, and then attempt to
! PEEK the message, ie; read it but leave it available
! to be re-read.
!
!********************************************************************
When using custom defined structures, it might be nice to know what they will be
used for.
!**************************************************
! Declare Variables of User Defined Structures
!**************************************************
DECLARE IOSB_STRUCT IOSB, ! I/O status blk &
ITEMLIST_2 SERVER.ITEMLST, ! Server item list &
ITEMLIST_2 SOCKOPT.ITEMLST, ! Socket options list &
ITEMLIST_2 REUSEADR.ITEMLST, ! Reuse adr list &
ITEMLIST_3 CLIENT.ITEMLST, ! Client item list &
SOCKET_OPTIONS LISTEN.OPTN, ! Socket options &
SOCK_ADDR CLIENT.ADR, ! Client IP adr/port &
SOCK_ADDR SERVER.ADR, ! Server IP adr/port &
BUFF CLIENT.NAME, ! Client name buffer &
BUFF SERVER.NAME, ! Server name buffer &
IP_ADR IP, ! Ip address &
BUFF MSG ! Message buffer
I consider the following rather terse. Either the programmer knows how to use
system services, or perhaps remedial training is called for.
!**************************************************
! Assign channels to 'TCPIP$DEVICE:'
!**************************************************
Dev$ = "TCPIP$DEVICE:"
Stat% = SYS$ASSIGN( Dev$ , ListenCh% , , )
If ( Stat% And SS$_NORMAL ) = 0%
Then E$ = FnVMSerr$( Stat% )
Print #KB%, "Unable to assign listener channel - "; E$
GoTo 4900
End If
Print #KB%, "Internal VMS channel for listener socket:"; ListenCh%
Stat% = SYS$ASSIGN( Dev$ , ClientCh% , , )
If ( Stat% And SS$_NORMAL ) = 0%
Then E$ = FnVMSerr$( Stat% )
Print #KB%, "Unable to assign client channel - "; E$
GoTo 4900
End If
However, when details might be helpful, there is usually never too much.
!**************************************************
! Create Listener socket
! Bind server's IP address and port # to listener
! socket, set socket as a passive socket
! Note: we used to do this in 2 calls, but can be combined
!**************************************************
LISTEN.OPTN::PROTOCOL% = TCPIP$C_TCP ! Listener socket optn
LISTEN.OPTN::TYP$ = Chr$(TCPIP$C_STREAM)
LISTEN.OPTN::AF$ = Chr$(TCPIP$C_AF_INET)
SOCKOPT.ITEMLST::LEN% = 8% ! Socket options buffer
SOCKOPT.ITEMLST::TYP% = TCPIP$C_SOCKOPT
SOCKOPT.ITEMLST::ADR% = Loc(REUSEADR.ITEMLST::Len%)
REUSEADR.ITEMLST::LEN% = 4% ! Reuse adr (port #)
REUSEADR.ITEMLST::TYP% = TCPIP$C_REUSEADDR
REUSEADR.ITEMLST::ADR% = Loc(ReuseAdrVal%)
ReuseAdrVal% = 1% ! Set to 'True'
SERVER.ITEMLST::LEN% = 16% ! Server item list
SERVER.ITEMLST::TYP% = TCPIP$C_SOCK_NAME
SERVER.ITEMLST::ADR% = Loc(SERVER.ADR::Fam%)
SERVER.ADR::Fam% = TCPIP$C_AF_INET ! Server Ip adr/port
SERVER.ADR::PORT% = SWAP%(ServerPort%)
SERVER.ADR::IP.ADR% = TCPIP$C_INADDR_ANY
SERVER.ADR::ZERO1% = 0%
SERVER.ADR::ZERO2% = 0%
BACKLOG% = 1%
Stat% = SYS$QIOW( , ! Event flag &
ListenCh% By Value, ! VMS channel &
IO$_SETCHAR By Value, ! Operation &
IOSB::Stat%, ! I/O status block &
, ! AST routine &
, ! AST parameter &
LISTEN.OPTN::Protocol%, ! P1 &
, ! P2 &
SERVER.ITEMLST::Len%, ! P3 - local socket nam
e &
BACKLOG% By Value, ! P4 - connection backl
og &
SOCKOPT.ITEMLST::Len%, ! P5 - socket options &
) ! P6
If ( Stat% And SS$_NORMAL ) = 0%
Then E$ = FnVMSerr$( Stat% )
Print #KB%, "Unable to queue create and bind listener socket - "
; E$
GoTo 4900
End If
If ( IOSB::Stat% And SS$_NORMAL ) = 0%
Then Stat% = IOSB::Stat%
E$ = FnVMSerr$( Stat% )
Print #KB%, "Unable to create and bind listener socket - "; E$
GoTo 4900
End If
My opinion is, the above is essential, without it, there would be much studying
of code, wondering what is being referenced, and such. I always use one line
for each argument in a QIO and such, which makes it very clear what is
happening. Without that, even the best will still have some "fun" reading the
code to figure out what is happening.
--
David Froble Tel: 724-529-0450
Dave Froble Enterprises, Inc. E-Mail: davef at tsoft-inc.com
DFE Ultralights, Inc.
170 Grimplin Road
Vanderbilt, PA 15486
More information about the Info-vax
mailing list